diff -u -r -N xemacs-21.4.18/ChangeLog xemacs-21.4.19/ChangeLog --- xemacs-21.4.18/ChangeLog 2005-12-03 13:55:13.000000000 -0500 +++ xemacs-21.4.19/ChangeLog 2006-01-28 18:58:28.000000000 -0500 @@ -1,3 +1,39 @@ +2006-01-28 Vin Shelton + + * XEmacs 21.4.19 is released + +2006-01-28 Vin Shelton + + * etc/package-index.LATEST.gpg: Updated with latest package data. + +2005-12-18 Ilya N. Golubev + + Merge from 21.5. + * configure.in: Fixed `LDAP_OPT_ON' libraries configuration + introduced in local 2005-03-13 change of `configure.in'. However, + do not check for internal `-lber' `ber_pvt_opt_on' symbol as done + in upstream. This symbol is not part of any published interface, + it may exist or not exist, depending on openldap version. Cryptic + comment before using it in upstream 21.5 source did not state + precisely under which circumstances checking for it was useful, + which sort of user code tried to link the symbol. So in local + 21.5 dismissed both the code and the comment without writing a + cleaner equivalent. + * etc/NEWS: Document. + +2005-12-13 Vin Shelton + + * etc/package-index.LATEST.gpg: Updated with latest package data. + +2005-12-04 Vin Shelton + + * etc/OXYMORONS: insert 'Social Property' for 21.4.18. + * etc/NEWS: document motif deprecation and defaulting + --with-widgets to off. + +2005-12-04 Ville Skyttä + * etc/PACKAGES: Fix description of xetla. + 2005-12-03 Vin Shelton * XEmacs 21.4.18 is released @@ -20,7 +56,7 @@ 2005-03-12 Aidan Kehoe * configure.in (XE_COMPUTE_RUNPATH): Check XtRegisterDrawable - availability. + availability. 2005-04-11 Norbert Koch @@ -176,10 +212,10 @@ 2004-01-25 Steve Youngs * etc/package-index.LATEST.gpg: New, replaces - `package-index.LATEST.pgp'. + `package-index.LATEST.pgp'. * etc/package-index.LATEST.pgp: Removed, replaced with - `package-index.LATEST.gpg'. + `package-index.LATEST.gpg'. 2004-01-20 Jerry James @@ -275,7 +311,7 @@ 2003-07-03 Stephen J. Turnbull - * etc/README.HYPERBOLE: + * etc/README.HYPERBOLE: * etc/README.OO-BROWSER: Update. @@ -307,7 +343,7 @@ 2003-03-20 Stephen J. Turnbull - * configure.in (INTPTR_T_IN_CYGWIN_TYPES_H): + * configure.in (INTPTR_T_IN_CYGWIN_TYPES_H): Cygwin defines these types in . Detect and don't duplicate the definition. @@ -346,7 +382,7 @@ gcc changed the name of the `-mthreads' option to `-pthread' on 2000-06-12. - Be more careful when appending "_r" to various names of xlc, + Be more careful when appending "_r" to various names of xlc, so that users can specify --compiler=/absolute/path/to/xlc 2003-01-27 Martin Buchholz @@ -356,7 +392,7 @@ 2003-01-27 Martin Buchholz - * configure.in (athena_3d): + * configure.in (athena_3d): AC_CHECK_LIB must always take a function as argument, never a global variable. Some linkers can tell the difference. So change: @@ -395,7 +431,7 @@ 2003-01-05 Rick Rankin - * configure.in: Add -lkernel32 to the list of system libraries + * configure.in: Add -lkernel32 to the list of system libraries linked under Cygwin. Needed for IsBadReadPtr(). 2003-01-03 Stephen J. Turnbull @@ -404,8 +440,8 @@ 2003-01-02 Stephen J. Turnbull - * configure.in (Generate Installation): - * configure.usage (--use-union-type): + * configure.in (Generate Installation): + * configure.usage (--use-union-type): * PROBLEMS (XEmacs crashes mysteriously): Deprecate --use-union-type for production builds. @@ -440,7 +476,7 @@ 2002-10-31 John Paul Wallington - * info/dir (File): button1 on a highlighted word doesn't + * info/dir (File): button1 on a highlighted word doesn't follow that cross-reference. 2002-11-11 Stephen J. Turnbull @@ -471,7 +507,7 @@ 2002-10-23 Stephen J. Turnbull * Makefile.in.in (lisp/auto-autoloads.el): - (lisp/custom-load.el): + (lisp/custom-load.el): Use -no-autoloads for these targets; can't load 'em if they ain't. 2002-10-18 Stephen J. Turnbull @@ -508,7 +544,7 @@ * configure.in (Check for POSIX functions): New section head. getaddrinfo is detected on HP-UX 11.XX, but appears to be non-functional. Disable it. Based on work by Darryl Okahata. - + 2002-09-27 Stephen J. Turnbull * PROBLEMS (Running, General): Missing charset in FontSet warnings. @@ -629,7 +665,7 @@ * configure.in: Detect MacOS/X "Darwin". Thanks to Greg Parker . - + 2002-03-30 Steve Youngs * etc/package-index.LATEST.pgp: Update to current reality. @@ -650,7 +686,7 @@ 2001-12-13 William M. Perry * configure.in (GTK): add -Wno-shadow. - + 2002-02-04 Stephen J. Turnbull * etc/BETA: Synch to 21.5. @@ -736,8 +772,8 @@ * configure.usage (--with-dragndrop): added GTK to list of protocols * configure.usage (--mail-locking): added `locking' or `mmdf'. to list of options - - + + 2001-09-25 Didier Verna * configure.ac: new. Autoconf 2.5x guard. @@ -831,7 +867,7 @@ 2001-05-04 Martin Buchholz - * configure.in (opsys): + * configure.in (opsys): Use lower-case `uname -s` as the default value for opsys. The previous code effectively did the non-sensical opsys=$canonical because [] magically disappear in configure.in. @@ -937,14 +973,14 @@ * etc/OXYMORONS: Add 2 oxymorons, clean up numbering, close RFC. * etc/NEWS: Fix typo. - + * configure.in: * configure: Fix typo, add -Wsign-compare if GCC, run autoconf. 2001-03-23 Stephen J. Turnbull - * etc/gnuserv.1 (UNIX_DOMAIN_SOCKETS: + * etc/gnuserv.1 (UNIX_DOMAIN_SOCKETS: * PROBLEMS (Problems with running XEmacs): Document TMPDIR lossage in gnuserv/gnuclient. diff -u -r -N xemacs-21.4.18/configure xemacs-21.4.19/configure --- xemacs-21.4.18/configure 2005-11-30 18:58:07.000000000 -0500 +++ xemacs-21.4.19/configure 2005-12-23 19:47:36.000000000 -0500 @@ -8039,6 +8039,102 @@ fi + if test yes = "$with_ldap" -a yes != "$ldap_needs_lber";then + echo $ac_n "checking for LDAP_OPT_ON definition""... $ac_c" 1>&6 +echo "configure:8045: checking for LDAP_OPT_ON definition" >&5 + +cat > conftest.$ac_ext < +#include +#ifdef LDAP_OPT_ON +/* Relying on const defined by ac_c_const (upper case). */ +const void *const v = LDAP_OPT_ON; +#else /* !defined (LDAP_OPT_ON) */ +choke me +#endif /* !defined (LDAP_OPT_ON) */ +int main() { + +; return 0; } +EOF +if { (eval echo configure:8062: \"$ac_compile\") 1>&5; (eval $ac_compile) 2>&5; }; then + rm -rf conftest* + xe_cv_have_LDAP_OPT_ON=yes +else + echo "configure: failed program was:" >&5 + cat conftest.$ac_ext >&5 + rm -rf conftest* + xe_cv_have_LDAP_OPT_ON=no +fi +rm -f conftest* + +echo "$ac_t""$xe_cv_have_LDAP_OPT_ON" 1>&6 + if test yes = "$xe_cv_have_LDAP_OPT_ON";then + echo $ac_n "checking LDAP_OPT_ON linking""... $ac_c" 1>&6 +echo "configure:8076: checking LDAP_OPT_ON linking" >&5 + +xe_save_LIBS="$LIBS" + LIBS="-lldap $LIBS" +cat > conftest.$ac_ext < +#include +const void *const v = LDAP_OPT_ON; +int main() { + +; return 0; } +EOF +if { (eval echo configure:8090: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then + rm -rf conftest* + xe_cv_LDAP_OPT_ON_links=yes +else + echo "configure: failed program was:" >&5 + cat conftest.$ac_ext >&5 + rm -rf conftest* + xe_cv_LDAP_OPT_ON_links=no +fi +rm -f conftest* + LIBS="$xe_save_LIBS" + +echo "$ac_t""$xe_cv_LDAP_OPT_ON_links" 1>&6 + if test yes != "$xe_cv_LDAP_OPT_ON_links";then + ldap_needs_lber=yes ldap_other_libs=-llber + echo $ac_n "checking LDAP_OPT_ON linking with -llber""... $ac_c" 1>&6 +echo "configure:8106: checking LDAP_OPT_ON linking with -llber" >&5 + +xe_save_LIBS="$LIBS" + LIBS="-lldap $ldap_other_libs $LIBS" +cat > conftest.$ac_ext < +#include +const void *const v = LDAP_OPT_ON; +int main() { + +; return 0; } +EOF +if { (eval echo configure:8120: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then + rm -rf conftest* + xe_cv_LDAP_OPT_ON_links_w_lber=yes +else + echo "configure: failed program was:" >&5 + cat conftest.$ac_ext >&5 + rm -rf conftest* + xe_cv_LDAP_OPT_ON_links_w_lber=no +fi +rm -f conftest* + LIBS="$xe_save_LIBS" + +echo "$ac_t""$xe_cv_LDAP_OPT_ON_links_w_lber" 1>&6 + if test yes != "$xe_cv_LDAP_OPT_ON_links_w_lber";then + with_ldap=no + fi + fi + fi + fi if test yes = "$with_ldap";then if test yes = "$ldap_needs_des";then ldap_libs="-ldes $ldap_libs" && if test "$extra_verbose" = "yes"; then echo " Prepending \"-ldes\" to \$ldap_libs"; fi @@ -8056,10 +8152,10 @@ else save_LIBS="$LIBS" LIBS="$ldap_libs $LIBS" echo $ac_n "checking for ldap_open""... $ac_c" 1>&6 -echo "configure:8060: checking for ldap_open" >&5 +echo "configure:8156: checking for ldap_open" >&5 cat > conftest.$ac_ext <&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then +if { (eval echo configure:8182: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then rm -rf conftest* eval "ac_cv_func_ldap_open=yes" else @@ -8122,10 +8218,10 @@ for ac_func in ldap_set_option ldap_get_lderrno ldap_result2error ldap_parse_result do echo $ac_n "checking for $ac_func""... $ac_c" 1>&6 -echo "configure:8126: checking for $ac_func" >&5 +echo "configure:8222: checking for $ac_func" >&5 cat > conftest.$ac_ext <&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then +if { (eval echo configure:8248: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then rm -rf conftest* eval "ac_cv_func_$ac_func=yes" else @@ -8179,20 +8275,20 @@ if test "$with_postgresql" != "no"; then echo "checking for PostgreSQL" 1>&6 -echo "configure:8183: checking for PostgreSQL" >&5 +echo "configure:8279: checking for PostgreSQL" >&5 for header_dir in "" "pgsql/" "postgresql/"; do ac_safe=`echo "${header_dir}libpq-fe.h" | sed 'y%./+-%__p_%'` echo $ac_n "checking for ${header_dir}libpq-fe.h""... $ac_c" 1>&6 -echo "configure:8188: checking for ${header_dir}libpq-fe.h" >&5 +echo "configure:8284: checking for ${header_dir}libpq-fe.h" >&5 cat > conftest.$ac_ext < EOF ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out" -{ (eval echo configure:8196: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; } +{ (eval echo configure:8292: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; } ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"` if test -z "$ac_err"; then rm -rf conftest* @@ -8216,12 +8312,12 @@ test -n "$libpq_fe_h_file" && { echo $ac_n "checking for PQconnectdb in -lpq""... $ac_c" 1>&6 -echo "configure:8220: checking for PQconnectdb in -lpq" >&5 +echo "configure:8316: checking for PQconnectdb in -lpq" >&5 ac_lib_var=`echo pq'_'PQconnectdb | sed 'y%./+-%__p_%'` xe_check_libs=" -lpq " cat > conftest.$ac_ext <&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then +if { (eval echo configure:8332: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then rm -rf conftest* eval "ac_cv_lib_$ac_lib_var=yes" else @@ -8265,12 +8361,12 @@ echo $ac_n "checking for PQconnectStart in -lpq""... $ac_c" 1>&6 -echo "configure:8269: checking for PQconnectStart in -lpq" >&5 +echo "configure:8365: checking for PQconnectStart in -lpq" >&5 ac_lib_var=`echo pq'_'PQconnectStart | sed 'y%./+-%__p_%'` xe_check_libs=" -lpq " cat > conftest.$ac_ext <&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then +if { (eval echo configure:8381: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then rm -rf conftest* eval "ac_cv_lib_$ac_lib_var=yes" else @@ -8329,7 +8425,7 @@ if test "$window_system" != "none"; then echo "checking for graphics libraries" 1>&6 -echo "configure:8333: checking for graphics libraries" >&5 +echo "configure:8429: checking for graphics libraries" >&5 libpath_xpm= incpath_xpm= @@ -8355,10 +8451,10 @@ CFLAGS=""$incpath_xpm" $CFLAGS" && if test "$extra_verbose" = "yes"; then echo " Prepending \""$incpath_xpm"\" to \$CFLAGS"; fi LDFLAGS=""$libpath_xpm" $LDFLAGS" && if test "$extra_verbose" = "yes"; then echo " Prepending \""$libpath_xpm"\" to \$LDFLAGS"; fi echo $ac_n "checking for Xpm - no older than 3.4f""... $ac_c" 1>&6 -echo "configure:8359: checking for Xpm - no older than 3.4f" >&5 +echo "configure:8455: checking for Xpm - no older than 3.4f" >&5 xe_check_libs=-lXpm cat > conftest.$ac_ext < @@ -8367,7 +8463,7 @@ XpmIncludeVersion != XpmLibraryVersion() ? 1 : XpmIncludeVersion < 30406 ? 2 : 0 ;} EOF -if { (eval echo configure:8371: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest && (./conftest; exit $?) 2>&5 +if { (eval echo configure:8467: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest && (./conftest; exit $?) 2>&5 then ./conftest dummy_arg; xpm_status=$?; if test "$xpm_status" = "0"; then @@ -8411,17 +8507,17 @@ libs_x="-lXpm $libs_x" && if test "$extra_verbose" = "yes"; then echo " Prepending \"-lXpm\" to \$libs_x"; fi CFLAGS=""$incpath_xpm" $CFLAGS" && if test "$extra_verbose" = "yes"; then echo " Prepending \""$incpath_xpm"\" to \$CFLAGS"; fi echo $ac_n "checking for \"FOR_MSW\" xpm""... $ac_c" 1>&6 -echo "configure:8415: checking for \"FOR_MSW\" xpm" >&5 +echo "configure:8511: checking for \"FOR_MSW\" xpm" >&5 xe_check_libs=-lXpm cat > conftest.$ac_ext <&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then +if { (eval echo configure:8521: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then rm -rf conftest* xpm_for_msw=no else @@ -8447,15 +8543,15 @@ test -z "$with_xface" && { ac_safe=`echo "compface.h" | sed 'y%./+-%__p_%'` echo $ac_n "checking for compface.h""... $ac_c" 1>&6 -echo "configure:8451: checking for compface.h" >&5 +echo "configure:8547: checking for compface.h" >&5 cat > conftest.$ac_ext < EOF ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out" -{ (eval echo configure:8459: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; } +{ (eval echo configure:8555: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; } ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"` if test -z "$ac_err"; then rm -rf conftest* @@ -8478,12 +8574,12 @@ } test -z "$with_xface" && { echo $ac_n "checking for UnGenFace in -lcompface""... $ac_c" 1>&6 -echo "configure:8482: checking for UnGenFace in -lcompface" >&5 +echo "configure:8578: checking for UnGenFace in -lcompface" >&5 ac_lib_var=`echo compface'_'UnGenFace | sed 'y%./+-%__p_%'` xe_check_libs=" -lcompface " cat > conftest.$ac_ext <&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then +if { (eval echo configure:8594: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then rm -rf conftest* eval "ac_cv_lib_$ac_lib_var=yes" else @@ -8546,12 +8642,12 @@ if test "$with_png $with_tiff" != "no no"; then echo $ac_n "checking for inflate in -lc""... $ac_c" 1>&6 -echo "configure:8550: checking for inflate in -lc" >&5 +echo "configure:8646: checking for inflate in -lc" >&5 ac_lib_var=`echo c'_'inflate | sed 'y%./+-%__p_%'` xe_check_libs=" -lc " cat > conftest.$ac_ext <&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then +if { (eval echo configure:8662: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then rm -rf conftest* eval "ac_cv_lib_$ac_lib_var=yes" else @@ -8581,12 +8677,12 @@ echo "$ac_t""no" 1>&6 echo $ac_n "checking for inflate in -lz""... $ac_c" 1>&6 -echo "configure:8585: checking for inflate in -lz" >&5 +echo "configure:8681: checking for inflate in -lz" >&5 ac_lib_var=`echo z'_'inflate | sed 'y%./+-%__p_%'` xe_check_libs=" -lz " cat > conftest.$ac_ext <&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then +if { (eval echo configure:8697: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then rm -rf conftest* eval "ac_cv_lib_$ac_lib_var=yes" else @@ -8616,12 +8712,12 @@ echo "$ac_t""no" 1>&6 echo $ac_n "checking for inflate in -lgz""... $ac_c" 1>&6 -echo "configure:8620: checking for inflate in -lgz" >&5 +echo "configure:8716: checking for inflate in -lgz" >&5 ac_lib_var=`echo gz'_'inflate | sed 'y%./+-%__p_%'` xe_check_libs=" -lgz " cat > conftest.$ac_ext <&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then +if { (eval echo configure:8732: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then rm -rf conftest* eval "ac_cv_lib_$ac_lib_var=yes" else @@ -8662,15 +8758,15 @@ test -z "$with_jpeg" && { ac_safe=`echo "jpeglib.h" | sed 'y%./+-%__p_%'` echo $ac_n "checking for jpeglib.h""... $ac_c" 1>&6 -echo "configure:8666: checking for jpeglib.h" >&5 +echo "configure:8762: checking for jpeglib.h" >&5 cat > conftest.$ac_ext < EOF ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out" -{ (eval echo configure:8674: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; } +{ (eval echo configure:8770: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; } ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"` if test -z "$ac_err"; then rm -rf conftest* @@ -8693,12 +8789,12 @@ } test -z "$with_jpeg" && { echo $ac_n "checking for jpeg_destroy_decompress in -ljpeg""... $ac_c" 1>&6 -echo "configure:8697: checking for jpeg_destroy_decompress in -ljpeg" >&5 +echo "configure:8793: checking for jpeg_destroy_decompress in -ljpeg" >&5 ac_lib_var=`echo jpeg'_'jpeg_destroy_decompress | sed 'y%./+-%__p_%'` xe_check_libs=" -ljpeg " cat > conftest.$ac_ext <&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then +if { (eval echo configure:8809: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then rm -rf conftest* eval "ac_cv_lib_$ac_lib_var=yes" else @@ -8745,10 +8841,10 @@ png_problem="" test -z "$with_png" && { echo $ac_n "checking for pow""... $ac_c" 1>&6 -echo "configure:8749: checking for pow" >&5 +echo "configure:8845: checking for pow" >&5 cat > conftest.$ac_ext <&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then +if { (eval echo configure:8871: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then rm -rf conftest* eval "ac_cv_func_pow=yes" else @@ -8792,15 +8888,15 @@ } test -z "$with_png" && { ac_safe=`echo "png.h" | sed 'y%./+-%__p_%'` echo $ac_n "checking for png.h""... $ac_c" 1>&6 -echo "configure:8796: checking for png.h" >&5 +echo "configure:8892: checking for png.h" >&5 cat > conftest.$ac_ext < EOF ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out" -{ (eval echo configure:8804: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; } +{ (eval echo configure:8900: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; } ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"` if test -z "$ac_err"; then rm -rf conftest* @@ -8823,12 +8919,12 @@ } test -z "$with_png" && { echo $ac_n "checking for png_read_image in -lpng""... $ac_c" 1>&6 -echo "configure:8827: checking for png_read_image in -lpng" >&5 +echo "configure:8923: checking for png_read_image in -lpng" >&5 ac_lib_var=`echo png'_'png_read_image | sed 'y%./+-%__p_%'` xe_check_libs=" -lpng " cat > conftest.$ac_ext <&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then +if { (eval echo configure:8939: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then rm -rf conftest* eval "ac_cv_lib_$ac_lib_var=yes" else @@ -8862,10 +8958,10 @@ } if test -z "$with_png"; then echo $ac_n "checking for workable png version information""... $ac_c" 1>&6 -echo "configure:8866: checking for workable png version information" >&5 +echo "configure:8962: checking for workable png version information" >&5 xe_check_libs="-lpng -lz" cat > conftest.$ac_ext < int main(int c, char **v) { @@ -8873,7 +8969,7 @@ if (strcmp(png_libpng_ver, PNG_LIBPNG_VER_STRING) != 0) return 1; return (PNG_LIBPNG_VER < 10002) ? 2 : 0 ;} EOF -if { (eval echo configure:8877: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest && (./conftest; exit $?) 2>&5 +if { (eval echo configure:8973: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest && (./conftest; exit $?) 2>&5 then ./conftest dummy_arg; png_status=$?; if test "$png_status" = "0"; then @@ -8916,15 +9012,15 @@ test -z "$with_tiff" && { ac_safe=`echo "tiffio.h" | sed 'y%./+-%__p_%'` echo $ac_n "checking for tiffio.h""... $ac_c" 1>&6 -echo "configure:8920: checking for tiffio.h" >&5 +echo "configure:9016: checking for tiffio.h" >&5 cat > conftest.$ac_ext < EOF ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out" -{ (eval echo configure:8928: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; } +{ (eval echo configure:9024: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; } ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"` if test -z "$ac_err"; then rm -rf conftest* @@ -8947,12 +9043,12 @@ } test -z "$with_tiff" && { echo $ac_n "checking for TIFFClientOpen in -ltiff""... $ac_c" 1>&6 -echo "configure:8951: checking for TIFFClientOpen in -ltiff" >&5 +echo "configure:9047: checking for TIFFClientOpen in -ltiff" >&5 ac_lib_var=`echo tiff'_'TIFFClientOpen | sed 'y%./+-%__p_%'` xe_check_libs=" -ltiff " cat > conftest.$ac_ext <&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then +if { (eval echo configure:9063: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then rm -rf conftest* eval "ac_cv_lib_$ac_lib_var=yes" else @@ -9002,15 +9098,15 @@ if test "$with_gtk" = "yes"; then test -z "$with_xface" && { ac_safe=`echo "compface.h" | sed 'y%./+-%__p_%'` echo $ac_n "checking for compface.h""... $ac_c" 1>&6 -echo "configure:9006: checking for compface.h" >&5 +echo "configure:9102: checking for compface.h" >&5 cat > conftest.$ac_ext < EOF ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out" -{ (eval echo configure:9014: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; } +{ (eval echo configure:9110: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; } ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"` if test -z "$ac_err"; then rm -rf conftest* @@ -9033,12 +9129,12 @@ } test -z "$with_xface" && { echo $ac_n "checking for UnGenFace in -lcompface""... $ac_c" 1>&6 -echo "configure:9037: checking for UnGenFace in -lcompface" >&5 +echo "configure:9133: checking for UnGenFace in -lcompface" >&5 ac_lib_var=`echo compface'_'UnGenFace | sed 'y%./+-%__p_%'` xe_check_libs=" -lcompface " cat > conftest.$ac_ext <&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then +if { (eval echo configure:9149: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then rm -rf conftest* eval "ac_cv_lib_$ac_lib_var=yes" else @@ -9088,12 +9184,12 @@ if test "$with_x11" = "yes"; then echo "checking for X11 graphics libraries" 1>&6 -echo "configure:9092: checking for X11 graphics libraries" >&5 +echo "configure:9188: checking for X11 graphics libraries" >&5 fi if test "$with_x11" = "yes"; then echo "checking for the Athena widgets" 1>&6 -echo "configure:9097: checking for the Athena widgets" >&5 +echo "configure:9193: checking for the Athena widgets" >&5 case "$with_athena" in "xaw" | "") athena_variant=Xaw athena_3d=no ;; @@ -9109,12 +9205,12 @@ if test "$athena_3d" = "no"; then echo $ac_n "checking for XawScrollbarSetThumb in -l$athena_variant""... $ac_c" 1>&6 -echo "configure:9113: checking for XawScrollbarSetThumb in -l$athena_variant" >&5 +echo "configure:9209: checking for XawScrollbarSetThumb in -l$athena_variant" >&5 ac_lib_var=`echo $athena_variant'_'XawScrollbarSetThumb | sed 'y%./+-%__p_%'` xe_check_libs=" -l$athena_variant " cat > conftest.$ac_ext <&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then +if { (eval echo configure:9225: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then rm -rf conftest* eval "ac_cv_lib_$ac_lib_var=yes" else @@ -9141,12 +9237,12 @@ echo "$ac_t""yes" 1>&6 echo $ac_n "checking for $athena_3d_function in -l$athena_variant""... $ac_c" 1>&6 -echo "configure:9145: checking for $athena_3d_function in -l$athena_variant" >&5 +echo "configure:9241: checking for $athena_3d_function in -l$athena_variant" >&5 ac_lib_var=`echo $athena_variant'_'$athena_3d_function | sed 'y%./+-%__p_%'` xe_check_libs=" -l$athena_variant " cat > conftest.$ac_ext <&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then +if { (eval echo configure:9257: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then rm -rf conftest* eval "ac_cv_lib_$ac_lib_var=yes" else @@ -9188,12 +9284,12 @@ else echo $ac_n "checking for $athena_3d_function in -l$athena_variant""... $ac_c" 1>&6 -echo "configure:9192: checking for $athena_3d_function in -l$athena_variant" >&5 +echo "configure:9288: checking for $athena_3d_function in -l$athena_variant" >&5 ac_lib_var=`echo $athena_variant'_'$athena_3d_function | sed 'y%./+-%__p_%'` xe_check_libs=" -l$athena_variant " cat > conftest.$ac_ext <&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then +if { (eval echo configure:9304: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then rm -rf conftest* eval "ac_cv_lib_$ac_lib_var=yes" else @@ -9222,12 +9318,12 @@ else echo "$ac_t""no" 1>&6 echo $ac_n "checking for $athena_3d_function in -lXaw""... $ac_c" 1>&6 -echo "configure:9226: checking for $athena_3d_function in -lXaw" >&5 +echo "configure:9322: checking for $athena_3d_function in -lXaw" >&5 ac_lib_var=`echo Xaw'_'$athena_3d_function | sed 'y%./+-%__p_%'` xe_check_libs=" -lXaw " cat > conftest.$ac_ext <&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then +if { (eval echo configure:9338: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then rm -rf conftest* eval "ac_cv_lib_$ac_lib_var=yes" else @@ -9269,15 +9365,15 @@ if test "$athena_3d" = "no"; then ac_safe=`echo "X11/Xaw/ThreeD.h" | sed 'y%./+-%__p_%'` echo $ac_n "checking for X11/Xaw/ThreeD.h""... $ac_c" 1>&6 -echo "configure:9273: checking for X11/Xaw/ThreeD.h" >&5 +echo "configure:9369: checking for X11/Xaw/ThreeD.h" >&5 cat > conftest.$ac_ext < EOF ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out" -{ (eval echo configure:9281: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; } +{ (eval echo configure:9377: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; } ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"` if test -z "$ac_err"; then rm -rf conftest* @@ -9297,15 +9393,15 @@ echo "$ac_t""no" 1>&6 ac_safe=`echo "X11/Xaw/XawInit.h" | sed 'y%./+-%__p_%'` echo $ac_n "checking for X11/Xaw/XawInit.h""... $ac_c" 1>&6 -echo "configure:9301: checking for X11/Xaw/XawInit.h" >&5 +echo "configure:9397: checking for X11/Xaw/XawInit.h" >&5 cat > conftest.$ac_ext < EOF ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out" -{ (eval echo configure:9309: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; } +{ (eval echo configure:9405: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; } ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"` if test -z "$ac_err"; then rm -rf conftest* @@ -9331,15 +9427,15 @@ else ac_safe=`echo "X11/$athena_variant/XawInit.h" | sed 'y%./+-%__p_%'` echo $ac_n "checking for X11/$athena_variant/XawInit.h""... $ac_c" 1>&6 -echo "configure:9335: checking for X11/$athena_variant/XawInit.h" >&5 +echo "configure:9431: checking for X11/$athena_variant/XawInit.h" >&5 cat > conftest.$ac_ext < EOF ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out" -{ (eval echo configure:9343: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; } +{ (eval echo configure:9439: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; } ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"` if test -z "$ac_err"; then rm -rf conftest* @@ -9356,15 +9452,15 @@ echo "$ac_t""yes" 1>&6 ac_safe=`echo "X11/$athena_variant/ThreeD.h" | sed 'y%./+-%__p_%'` echo $ac_n "checking for X11/$athena_variant/ThreeD.h""... $ac_c" 1>&6 -echo "configure:9360: checking for X11/$athena_variant/ThreeD.h" >&5 +echo "configure:9456: checking for X11/$athena_variant/ThreeD.h" >&5 cat > conftest.$ac_ext < EOF ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out" -{ (eval echo configure:9368: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; } +{ (eval echo configure:9464: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; } ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"` if test -z "$ac_err"; then rm -rf conftest* @@ -9392,15 +9488,15 @@ if test -z "$athena_h_path"; then ac_safe=`echo "$athena_variant/XawInit.h" | sed 'y%./+-%__p_%'` echo $ac_n "checking for $athena_variant/XawInit.h""... $ac_c" 1>&6 -echo "configure:9396: checking for $athena_variant/XawInit.h" >&5 +echo "configure:9492: checking for $athena_variant/XawInit.h" >&5 cat > conftest.$ac_ext < EOF ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out" -{ (eval echo configure:9404: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; } +{ (eval echo configure:9500: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; } ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"` if test -z "$ac_err"; then rm -rf conftest* @@ -9417,15 +9513,15 @@ echo "$ac_t""yes" 1>&6 ac_safe=`echo "$athena_variant/ThreeD.h" | sed 'y%./+-%__p_%'` echo $ac_n "checking for $athena_variant/ThreeD.h""... $ac_c" 1>&6 -echo "configure:9421: checking for $athena_variant/ThreeD.h" >&5 +echo "configure:9517: checking for $athena_variant/ThreeD.h" >&5 cat > conftest.$ac_ext < EOF ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out" -{ (eval echo configure:9429: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; } +{ (eval echo configure:9525: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; } ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"` if test -z "$ac_err"; then rm -rf conftest* @@ -9454,15 +9550,15 @@ if test -z "$athena_h_path" -a "$athena_variant" != "Xaw3d"; then ac_safe=`echo "X11/Xaw3d/XawInit.h" | sed 'y%./+-%__p_%'` echo $ac_n "checking for X11/Xaw3d/XawInit.h""... $ac_c" 1>&6 -echo "configure:9458: checking for X11/Xaw3d/XawInit.h" >&5 +echo "configure:9554: checking for X11/Xaw3d/XawInit.h" >&5 cat > conftest.$ac_ext < EOF ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out" -{ (eval echo configure:9466: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; } +{ (eval echo configure:9562: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; } ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"` if test -z "$ac_err"; then rm -rf conftest* @@ -9479,15 +9575,15 @@ echo "$ac_t""yes" 1>&6 ac_safe=`echo "X11/Xaw3d/ThreeD.h" | sed 'y%./+-%__p_%'` echo $ac_n "checking for X11/Xaw3d/ThreeD.h""... $ac_c" 1>&6 -echo "configure:9483: checking for X11/Xaw3d/ThreeD.h" >&5 +echo "configure:9579: checking for X11/Xaw3d/ThreeD.h" >&5 cat > conftest.$ac_ext < EOF ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out" -{ (eval echo configure:9491: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; } +{ (eval echo configure:9587: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; } ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"` if test -z "$ac_err"; then rm -rf conftest* @@ -9519,15 +9615,15 @@ if test -z "$athena_h_path" -a "$athena_variant" != "Xaw3d"; then ac_safe=`echo "Xaw3d/XawInit.h" | sed 'y%./+-%__p_%'` echo $ac_n "checking for Xaw3d/XawInit.h""... $ac_c" 1>&6 -echo "configure:9523: checking for Xaw3d/XawInit.h" >&5 +echo "configure:9619: checking for Xaw3d/XawInit.h" >&5 cat > conftest.$ac_ext < EOF ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out" -{ (eval echo configure:9531: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; } +{ (eval echo configure:9627: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; } ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"` if test -z "$ac_err"; then rm -rf conftest* @@ -9544,15 +9640,15 @@ echo "$ac_t""yes" 1>&6 ac_safe=`echo "Xaw3d/ThreeD.h" | sed 'y%./+-%__p_%'` echo $ac_n "checking for Xaw3d/ThreeD.h""... $ac_c" 1>&6 -echo "configure:9548: checking for Xaw3d/ThreeD.h" >&5 +echo "configure:9644: checking for Xaw3d/ThreeD.h" >&5 cat > conftest.$ac_ext < EOF ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out" -{ (eval echo configure:9556: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; } +{ (eval echo configure:9652: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; } ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"` if test -z "$ac_err"; then rm -rf conftest* @@ -9584,15 +9680,15 @@ if test -z "$athena_h_path"; then ac_safe=`echo "X11/Xaw/ThreeD.h" | sed 'y%./+-%__p_%'` echo $ac_n "checking for X11/Xaw/ThreeD.h""... $ac_c" 1>&6 -echo "configure:9588: checking for X11/Xaw/ThreeD.h" >&5 +echo "configure:9684: checking for X11/Xaw/ThreeD.h" >&5 cat > conftest.$ac_ext < EOF ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out" -{ (eval echo configure:9596: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; } +{ (eval echo configure:9692: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; } ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"` if test -z "$ac_err"; then rm -rf conftest* @@ -9631,15 +9727,15 @@ if test "$with_x11" = "yes"; then ac_safe=`echo "Xm/Xm.h" | sed 'y%./+-%__p_%'` echo $ac_n "checking for Xm/Xm.h""... $ac_c" 1>&6 -echo "configure:9635: checking for Xm/Xm.h" >&5 +echo "configure:9731: checking for Xm/Xm.h" >&5 cat > conftest.$ac_ext < EOF ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out" -{ (eval echo configure:9643: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; } +{ (eval echo configure:9739: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; } ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"` if test -z "$ac_err"; then rm -rf conftest* @@ -9656,12 +9752,12 @@ echo "$ac_t""yes" 1>&6 echo $ac_n "checking for XmStringFree in -lXm""... $ac_c" 1>&6 -echo "configure:9660: checking for XmStringFree in -lXm" >&5 +echo "configure:9756: checking for XmStringFree in -lXm" >&5 ac_lib_var=`echo Xm'_'XmStringFree | sed 'y%./+-%__p_%'` xe_check_libs=" -lXm " cat > conftest.$ac_ext <&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then +if { (eval echo configure:9772: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then rm -rf conftest* eval "ac_cv_lib_$ac_lib_var=yes" else @@ -9701,9 +9797,9 @@ if test "$have_motif" = "yes"; then echo $ac_n "checking for Lesstif""... $ac_c" 1>&6 -echo "configure:9705: checking for Lesstif" >&5 +echo "configure:9801: checking for Lesstif" >&5 cat > conftest.$ac_ext < #ifdef LESSTIF_VERSION @@ -10149,7 +10245,7 @@ if test "$with_mule" = "yes" ; then echo "checking for Mule-related features" 1>&6 -echo "configure:10153: checking for Mule-related features" >&5 +echo "configure:10249: checking for Mule-related features" >&5 { test "$extra_verbose" = "yes" && cat << \EOF Defining MULE EOF @@ -10174,15 +10270,15 @@ do ac_safe=`echo "$ac_hdr" | sed 'y%./+-%__p_%'` echo $ac_n "checking for $ac_hdr""... $ac_c" 1>&6 -echo "configure:10178: checking for $ac_hdr" >&5 +echo "configure:10274: checking for $ac_hdr" >&5 cat > conftest.$ac_ext < EOF ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out" -{ (eval echo configure:10186: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; } +{ (eval echo configure:10282: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; } ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"` if test -z "$ac_err"; then rm -rf conftest* @@ -10213,12 +10309,12 @@ echo $ac_n "checking for strerror in -lintl""... $ac_c" 1>&6 -echo "configure:10217: checking for strerror in -lintl" >&5 +echo "configure:10313: checking for strerror in -lintl" >&5 ac_lib_var=`echo intl'_'strerror | sed 'y%./+-%__p_%'` xe_check_libs=" -lintl " cat > conftest.$ac_ext <&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then +if { (eval echo configure:10329: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then rm -rf conftest* eval "ac_cv_lib_$ac_lib_var=yes" else @@ -10262,18 +10358,18 @@ echo "checking for Mule input methods" 1>&6 -echo "configure:10266: checking for Mule input methods" >&5 +echo "configure:10362: checking for Mule input methods" >&5 case "$with_xim" in "" | "yes" ) echo "checking for XIM" 1>&6 -echo "configure:10269: checking for XIM" >&5 +echo "configure:10365: checking for XIM" >&5 echo $ac_n "checking for XOpenIM in -lX11""... $ac_c" 1>&6 -echo "configure:10272: checking for XOpenIM in -lX11" >&5 +echo "configure:10368: checking for XOpenIM in -lX11" >&5 ac_lib_var=`echo X11'_'XOpenIM | sed 'y%./+-%__p_%'` xe_check_libs=" -lX11 " cat > conftest.$ac_ext <&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then +if { (eval echo configure:10384: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then rm -rf conftest* eval "ac_cv_lib_$ac_lib_var=yes" else @@ -10308,12 +10404,12 @@ if test "$need_motif $have_lesstif" = "yes no"; then echo $ac_n "checking for XmImMbLookupString in -lXm""... $ac_c" 1>&6 -echo "configure:10312: checking for XmImMbLookupString in -lXm" >&5 +echo "configure:10408: checking for XmImMbLookupString in -lXm" >&5 ac_lib_var=`echo Xm'_'XmImMbLookupString | sed 'y%./+-%__p_%'` xe_check_libs=" -lXm " cat > conftest.$ac_ext <&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then +if { (eval echo configure:10424: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then rm -rf conftest* eval "ac_cv_lib_$ac_lib_var=yes" else @@ -10347,12 +10443,12 @@ elif test "$have_motif $have_lesstif $with_xim" = "yes no no"; then echo $ac_n "checking for XmImMbLookupString in -lXm""... $ac_c" 1>&6 -echo "configure:10351: checking for XmImMbLookupString in -lXm" >&5 +echo "configure:10447: checking for XmImMbLookupString in -lXm" >&5 ac_lib_var=`echo Xm'_'XmImMbLookupString | sed 'y%./+-%__p_%'` xe_check_libs=" -lXm " cat > conftest.$ac_ext <&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then +if { (eval echo configure:10463: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then rm -rf conftest* eval "ac_cv_lib_$ac_lib_var=yes" else @@ -10428,15 +10524,15 @@ if test "$with_xfs" = "yes" ; then echo "checking for XFontSet" 1>&6 -echo "configure:10432: checking for XFontSet" >&5 +echo "configure:10528: checking for XFontSet" >&5 echo $ac_n "checking for XmbDrawString in -lX11""... $ac_c" 1>&6 -echo "configure:10435: checking for XmbDrawString in -lX11" >&5 +echo "configure:10531: checking for XmbDrawString in -lX11" >&5 ac_lib_var=`echo X11'_'XmbDrawString | sed 'y%./+-%__p_%'` xe_check_libs=" -lX11 " cat > conftest.$ac_ext <&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then +if { (eval echo configure:10547: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then rm -rf conftest* eval "ac_cv_lib_$ac_lib_var=yes" else @@ -10487,15 +10583,15 @@ test "$with_wnn6" = "yes" && with_wnn=yes # wnn6 implies wnn support test -z "$with_wnn" && { ac_safe=`echo "wnn/jllib.h" | sed 'y%./+-%__p_%'` echo $ac_n "checking for wnn/jllib.h""... $ac_c" 1>&6 -echo "configure:10491: checking for wnn/jllib.h" >&5 +echo "configure:10587: checking for wnn/jllib.h" >&5 cat > conftest.$ac_ext < EOF ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out" -{ (eval echo configure:10499: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; } +{ (eval echo configure:10595: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; } ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"` if test -z "$ac_err"; then rm -rf conftest* @@ -10518,15 +10614,15 @@ } test -z "$with_wnn" && { ac_safe=`echo "wnn/commonhd.h" | sed 'y%./+-%__p_%'` echo $ac_n "checking for wnn/commonhd.h""... $ac_c" 1>&6 -echo "configure:10522: checking for wnn/commonhd.h" >&5 +echo "configure:10618: checking for wnn/commonhd.h" >&5 cat > conftest.$ac_ext < EOF ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out" -{ (eval echo configure:10530: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; } +{ (eval echo configure:10626: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; } ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"` if test -z "$ac_err"; then rm -rf conftest* @@ -10551,10 +10647,10 @@ for ac_func in crypt do echo $ac_n "checking for $ac_func""... $ac_c" 1>&6 -echo "configure:10555: checking for $ac_func" >&5 +echo "configure:10651: checking for $ac_func" >&5 cat > conftest.$ac_ext <&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then +if { (eval echo configure:10677: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then rm -rf conftest* eval "ac_cv_func_$ac_func=yes" else @@ -10606,12 +10702,12 @@ test "$ac_cv_func_crypt" != "yes" && { echo $ac_n "checking for crypt in -lcrypt""... $ac_c" 1>&6 -echo "configure:10610: checking for crypt in -lcrypt" >&5 +echo "configure:10706: checking for crypt in -lcrypt" >&5 ac_lib_var=`echo crypt'_'crypt | sed 'y%./+-%__p_%'` xe_check_libs=" -lcrypt " cat > conftest.$ac_ext <&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then +if { (eval echo configure:10722: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then rm -rf conftest* eval "ac_cv_lib_$ac_lib_var=yes" else @@ -10657,12 +10753,12 @@ if test -z "$with_wnn" -o "$with_wnn" = "yes"; then echo $ac_n "checking for jl_dic_list_e in -lwnn""... $ac_c" 1>&6 -echo "configure:10661: checking for jl_dic_list_e in -lwnn" >&5 +echo "configure:10757: checking for jl_dic_list_e in -lwnn" >&5 ac_lib_var=`echo wnn'_'jl_dic_list_e | sed 'y%./+-%__p_%'` xe_check_libs=" -lwnn " cat > conftest.$ac_ext <&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then +if { (eval echo configure:10773: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then rm -rf conftest* eval "ac_cv_lib_$ac_lib_var=yes" else @@ -10691,12 +10787,12 @@ else echo "$ac_t""no" 1>&6 echo $ac_n "checking for jl_dic_list_e in -lwnn4""... $ac_c" 1>&6 -echo "configure:10695: checking for jl_dic_list_e in -lwnn4" >&5 +echo "configure:10791: checking for jl_dic_list_e in -lwnn4" >&5 ac_lib_var=`echo wnn4'_'jl_dic_list_e | sed 'y%./+-%__p_%'` xe_check_libs=" -lwnn4 " cat > conftest.$ac_ext <&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then +if { (eval echo configure:10807: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then rm -rf conftest* eval "ac_cv_lib_$ac_lib_var=yes" else @@ -10725,12 +10821,12 @@ else echo "$ac_t""no" 1>&6 echo $ac_n "checking for jl_dic_list_e in -lwnn6""... $ac_c" 1>&6 -echo "configure:10729: checking for jl_dic_list_e in -lwnn6" >&5 +echo "configure:10825: checking for jl_dic_list_e in -lwnn6" >&5 ac_lib_var=`echo wnn6'_'jl_dic_list_e | sed 'y%./+-%__p_%'` xe_check_libs=" -lwnn6 " cat > conftest.$ac_ext <&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then +if { (eval echo configure:10841: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then rm -rf conftest* eval "ac_cv_lib_$ac_lib_var=yes" else @@ -10759,12 +10855,12 @@ else echo "$ac_t""no" 1>&6 echo $ac_n "checking for dic_list_e in -lwnn6_fromsrc""... $ac_c" 1>&6 -echo "configure:10763: checking for dic_list_e in -lwnn6_fromsrc" >&5 +echo "configure:10859: checking for dic_list_e in -lwnn6_fromsrc" >&5 ac_lib_var=`echo wnn6_fromsrc'_'dic_list_e | sed 'y%./+-%__p_%'` xe_check_libs=" -lwnn6_fromsrc " cat > conftest.$ac_ext <&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then +if { (eval echo configure:10875: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then rm -rf conftest* eval "ac_cv_lib_$ac_lib_var=yes" else @@ -10823,12 +10919,12 @@ if test "$with_wnn6" != "no"; then echo $ac_n "checking for jl_fi_dic_list in -l$libwnn""... $ac_c" 1>&6 -echo "configure:10827: checking for jl_fi_dic_list in -l$libwnn" >&5 +echo "configure:10923: checking for jl_fi_dic_list in -l$libwnn" >&5 ac_lib_var=`echo $libwnn'_'jl_fi_dic_list | sed 'y%./+-%__p_%'` xe_check_libs=" -l$libwnn " cat > conftest.$ac_ext <&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then +if { (eval echo configure:10939: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then rm -rf conftest* eval "ac_cv_lib_$ac_lib_var=yes" else @@ -10874,15 +10970,15 @@ if test "$with_canna" != "no"; then ac_safe=`echo "canna/jrkanji.h" | sed 'y%./+-%__p_%'` echo $ac_n "checking for canna/jrkanji.h""... $ac_c" 1>&6 -echo "configure:10878: checking for canna/jrkanji.h" >&5 +echo "configure:10974: checking for canna/jrkanji.h" >&5 cat > conftest.$ac_ext < EOF ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out" -{ (eval echo configure:10886: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; } +{ (eval echo configure:10982: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; } ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"` if test -z "$ac_err"; then rm -rf conftest* @@ -10909,15 +11005,15 @@ c_switch_site="$c_switch_site -I/usr/local/canna/include" ac_safe=`echo "canna/jrkanji.h" | sed 'y%./+-%__p_%'` echo $ac_n "checking for canna/jrkanji.h""... $ac_c" 1>&6 -echo "configure:10913: checking for canna/jrkanji.h" >&5 +echo "configure:11009: checking for canna/jrkanji.h" >&5 cat > conftest.$ac_ext < EOF ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out" -{ (eval echo configure:10921: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; } +{ (eval echo configure:11017: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; } ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"` if test -z "$ac_err"; then rm -rf conftest* @@ -10945,15 +11041,15 @@ test -z "$with_canna" && { ac_safe=`echo "canna/RK.h" | sed 'y%./+-%__p_%'` echo $ac_n "checking for canna/RK.h""... $ac_c" 1>&6 -echo "configure:10949: checking for canna/RK.h" >&5 +echo "configure:11045: checking for canna/RK.h" >&5 cat > conftest.$ac_ext < EOF ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out" -{ (eval echo configure:10957: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; } +{ (eval echo configure:11053: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; } ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"` if test -z "$ac_err"; then rm -rf conftest* @@ -10976,12 +11072,12 @@ } test -z "$with_canna" && { echo $ac_n "checking for RkBgnBun in -lRKC""... $ac_c" 1>&6 -echo "configure:10980: checking for RkBgnBun in -lRKC" >&5 +echo "configure:11076: checking for RkBgnBun in -lRKC" >&5 ac_lib_var=`echo RKC'_'RkBgnBun | sed 'y%./+-%__p_%'` xe_check_libs=" -lRKC " cat > conftest.$ac_ext <&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then +if { (eval echo configure:11092: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then rm -rf conftest* eval "ac_cv_lib_$ac_lib_var=yes" else @@ -11015,12 +11111,12 @@ } test -z "$with_canna" && { echo $ac_n "checking for jrKanjiControl in -lcanna""... $ac_c" 1>&6 -echo "configure:11019: checking for jrKanjiControl in -lcanna" >&5 +echo "configure:11115: checking for jrKanjiControl in -lcanna" >&5 ac_lib_var=`echo canna'_'jrKanjiControl | sed 'y%./+-%__p_%'` xe_check_libs=" -lcanna " cat > conftest.$ac_ext <&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then +if { (eval echo configure:11131: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then rm -rf conftest* eval "ac_cv_lib_$ac_lib_var=yes" else @@ -11080,12 +11176,12 @@ libs_x="-lXm $libs_x" && if test "$extra_verbose" = "yes"; then echo " Prepending \"-lXm\" to \$libs_x"; fi echo $ac_n "checking for layout_object_getvalue in -li18n""... $ac_c" 1>&6 -echo "configure:11084: checking for layout_object_getvalue in -li18n" >&5 +echo "configure:11180: checking for layout_object_getvalue in -li18n" >&5 ac_lib_var=`echo i18n'_'layout_object_getvalue | sed 'y%./+-%__p_%'` xe_check_libs=" -li18n " cat > conftest.$ac_ext <&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then +if { (eval echo configure:11196: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then rm -rf conftest* eval "ac_cv_lib_$ac_lib_var=yes" else @@ -11183,10 +11279,10 @@ for ac_func in cbrt closedir dup2 eaccess fmod fpathconf frexp ftime getaddrinfo gethostname getnameinfo getpagesize gettimeofday getcwd getwd logb lrand48 matherr mkdir mktime perror poll random rename res_init rint rmdir select setitimer setpgid setlocale setsid sigblock sighold sigprocmask snprintf stpcpy strerror tzset ulimit usleep waitpid vsnprintf fsync ftruncate umask do echo $ac_n "checking for $ac_func""... $ac_c" 1>&6 -echo "configure:11187: checking for $ac_func" >&5 +echo "configure:11283: checking for $ac_func" >&5 cat > conftest.$ac_ext <&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then +if { (eval echo configure:11309: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then rm -rf conftest* eval "ac_cv_func_$ac_func=yes" else @@ -11250,10 +11346,10 @@ for ac_func in getpt _getpty grantpt unlockpt ptsname killpg tcgetpgrp do echo $ac_n "checking for $ac_func""... $ac_c" 1>&6 -echo "configure:11254: checking for $ac_func" >&5 +echo "configure:11350: checking for $ac_func" >&5 cat > conftest.$ac_ext <&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then +if { (eval echo configure:11376: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then rm -rf conftest* eval "ac_cv_func_$ac_func=yes" else @@ -11305,10 +11401,10 @@ echo $ac_n "checking for openpty""... $ac_c" 1>&6 -echo "configure:11309: checking for openpty" >&5 +echo "configure:11405: checking for openpty" >&5 cat > conftest.$ac_ext <&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then +if { (eval echo configure:11431: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then rm -rf conftest* eval "ac_cv_func_openpty=yes" else @@ -11350,12 +11446,12 @@ echo $ac_n "checking for openpty in -lutil""... $ac_c" 1>&6 -echo "configure:11354: checking for openpty in -lutil" >&5 +echo "configure:11450: checking for openpty in -lutil" >&5 ac_lib_var=`echo util'_'openpty | sed 'y%./+-%__p_%'` xe_check_libs=" -lutil " cat > conftest.$ac_ext <&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then +if { (eval echo configure:11466: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then rm -rf conftest* eval "ac_cv_lib_$ac_lib_var=yes" else @@ -11401,15 +11497,15 @@ do ac_safe=`echo "$ac_hdr" | sed 'y%./+-%__p_%'` echo $ac_n "checking for $ac_hdr""... $ac_c" 1>&6 -echo "configure:11405: checking for $ac_hdr" >&5 +echo "configure:11501: checking for $ac_hdr" >&5 cat > conftest.$ac_ext < EOF ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out" -{ (eval echo configure:11413: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; } +{ (eval echo configure:11509: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; } ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"` if test -z "$ac_err"; then rm -rf conftest* @@ -11445,15 +11541,15 @@ do ac_safe=`echo "$ac_hdr" | sed 'y%./+-%__p_%'` echo $ac_n "checking for $ac_hdr""... $ac_c" 1>&6 -echo "configure:11449: checking for $ac_hdr" >&5 +echo "configure:11545: checking for $ac_hdr" >&5 cat > conftest.$ac_ext < EOF ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out" -{ (eval echo configure:11457: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; } +{ (eval echo configure:11553: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; } ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"` if test -z "$ac_err"; then rm -rf conftest* @@ -11486,10 +11582,10 @@ for ac_func in isastream do echo $ac_n "checking for $ac_func""... $ac_c" 1>&6 -echo "configure:11490: checking for $ac_func" >&5 +echo "configure:11586: checking for $ac_func" >&5 cat > conftest.$ac_ext <&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then +if { (eval echo configure:11612: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then rm -rf conftest* eval "ac_cv_func_$ac_func=yes" else @@ -11543,15 +11639,15 @@ do ac_safe=`echo "$ac_hdr" | sed 'y%./+-%__p_%'` echo $ac_n "checking for $ac_hdr""... $ac_c" 1>&6 -echo "configure:11547: checking for $ac_hdr" >&5 +echo "configure:11643: checking for $ac_hdr" >&5 cat > conftest.$ac_ext < EOF ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out" -{ (eval echo configure:11555: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; } +{ (eval echo configure:11651: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; } ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"` if test -z "$ac_err"; then rm -rf conftest* @@ -11588,10 +11684,10 @@ for ac_func in getloadavg do echo $ac_n "checking for $ac_func""... $ac_c" 1>&6 -echo "configure:11592: checking for $ac_func" >&5 +echo "configure:11688: checking for $ac_func" >&5 cat > conftest.$ac_ext <&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then +if { (eval echo configure:11714: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then rm -rf conftest* eval "ac_cv_func_$ac_func=yes" else @@ -11647,15 +11743,15 @@ do ac_safe=`echo "$ac_hdr" | sed 'y%./+-%__p_%'` echo $ac_n "checking for $ac_hdr""... $ac_c" 1>&6 -echo "configure:11651: checking for $ac_hdr" >&5 +echo "configure:11747: checking for $ac_hdr" >&5 cat > conftest.$ac_ext < EOF ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out" -{ (eval echo configure:11659: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; } +{ (eval echo configure:11755: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; } ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"` if test -z "$ac_err"; then rm -rf conftest* @@ -11691,12 +11787,12 @@ echo $ac_n "checking for kstat_open in -lkstat""... $ac_c" 1>&6 -echo "configure:11695: checking for kstat_open in -lkstat" >&5 +echo "configure:11791: checking for kstat_open in -lkstat" >&5 ac_lib_var=`echo kstat'_'kstat_open | sed 'y%./+-%__p_%'` xe_check_libs=" -lkstat " cat > conftest.$ac_ext <&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then +if { (eval echo configure:11807: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then rm -rf conftest* eval "ac_cv_lib_$ac_lib_var=yes" else @@ -11742,15 +11838,15 @@ do ac_safe=`echo "$ac_hdr" | sed 'y%./+-%__p_%'` echo $ac_n "checking for $ac_hdr""... $ac_c" 1>&6 -echo "configure:11746: checking for $ac_hdr" >&5 +echo "configure:11842: checking for $ac_hdr" >&5 cat > conftest.$ac_ext < EOF ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out" -{ (eval echo configure:11754: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; } +{ (eval echo configure:11850: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; } ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"` if test -z "$ac_err"; then rm -rf conftest* @@ -11782,12 +11878,12 @@ echo $ac_n "checking for kvm_read in -lkvm""... $ac_c" 1>&6 -echo "configure:11786: checking for kvm_read in -lkvm" >&5 +echo "configure:11882: checking for kvm_read in -lkvm" >&5 ac_lib_var=`echo kvm'_'kvm_read | sed 'y%./+-%__p_%'` xe_check_libs=" -lkvm " cat > conftest.$ac_ext <&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then +if { (eval echo configure:11898: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then rm -rf conftest* eval "ac_cv_lib_$ac_lib_var=yes" else @@ -11832,16 +11928,16 @@ fi echo $ac_n "checking whether netdb declares h_errno""... $ac_c" 1>&6 -echo "configure:11836: checking whether netdb declares h_errno" >&5 +echo "configure:11932: checking whether netdb declares h_errno" >&5 cat > conftest.$ac_ext < int main() { return h_errno; ; return 0; } EOF -if { (eval echo configure:11845: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then +if { (eval echo configure:11941: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then rm -rf conftest* echo "$ac_t""yes" 1>&6 { test "$extra_verbose" = "yes" && cat << \EOF @@ -11861,16 +11957,16 @@ rm -f conftest* echo $ac_n "checking for sigsetjmp""... $ac_c" 1>&6 -echo "configure:11865: checking for sigsetjmp" >&5 +echo "configure:11961: checking for sigsetjmp" >&5 cat > conftest.$ac_ext < int main() { sigjmp_buf bar; sigsetjmp (bar, 0); ; return 0; } EOF -if { (eval echo configure:11874: \"$ac_compile\") 1>&5; (eval $ac_compile) 2>&5; }; then +if { (eval echo configure:11970: \"$ac_compile\") 1>&5; (eval $ac_compile) 2>&5; }; then rm -rf conftest* echo "$ac_t""yes" 1>&6 { test "$extra_verbose" = "yes" && cat << \EOF @@ -11890,11 +11986,11 @@ rm -f conftest* echo $ac_n "checking whether localtime caches TZ""... $ac_c" 1>&6 -echo "configure:11894: checking whether localtime caches TZ" >&5 +echo "configure:11990: checking whether localtime caches TZ" >&5 if test "$ac_cv_func_tzset" = "yes"; then cat > conftest.$ac_ext < #if STDC_HEADERS @@ -11929,7 +12025,7 @@ exit (0); } EOF -if { (eval echo configure:11933: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest && (./conftest; exit $?) 2>&5 +if { (eval echo configure:12029: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest && (./conftest; exit $?) 2>&5 then emacs_cv_localtime_cache=no else @@ -11959,9 +12055,9 @@ if test "$HAVE_TIMEVAL" = "yes"; then echo $ac_n "checking whether gettimeofday accepts one or two arguments""... $ac_c" 1>&6 -echo "configure:11963: checking whether gettimeofday accepts one or two arguments" >&5 +echo "configure:12059: checking whether gettimeofday accepts one or two arguments" >&5 cat > conftest.$ac_ext <&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then +if { (eval echo configure:12082: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then rm -rf conftest* echo "$ac_t""two" 1>&6 else @@ -12004,19 +12100,19 @@ echo $ac_n "checking for inline""... $ac_c" 1>&6 -echo "configure:12008: checking for inline" >&5 +echo "configure:12104: checking for inline" >&5 ac_cv_c_inline=no for ac_kw in inline __inline__ __inline; do cat > conftest.$ac_ext <&5; (eval $ac_compile) 2>&5; }; then +if { (eval echo configure:12116: \"$ac_compile\") 1>&5; (eval $ac_compile) 2>&5; }; then rm -rf conftest* ac_cv_c_inline=$ac_kw; break else @@ -12057,17 +12153,17 @@ # The Ultrix 4.2 mips builtin alloca declared by alloca.h only works # for constant arguments. Useless! echo $ac_n "checking for working alloca.h""... $ac_c" 1>&6 -echo "configure:12061: checking for working alloca.h" >&5 +echo "configure:12157: checking for working alloca.h" >&5 cat > conftest.$ac_ext < int main() { char *p = alloca(2 * sizeof(int)); ; return 0; } EOF -if { (eval echo configure:12071: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then +if { (eval echo configure:12167: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then rm -rf conftest* ac_cv_header_alloca_h=yes else @@ -12091,10 +12187,10 @@ fi echo $ac_n "checking for alloca""... $ac_c" 1>&6 -echo "configure:12095: checking for alloca" >&5 +echo "configure:12191: checking for alloca" >&5 cat > conftest.$ac_ext <&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then +if { (eval echo configure:12222: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then rm -rf conftest* ac_cv_func_alloca_works=yes else @@ -12161,10 +12257,10 @@ echo $ac_n "checking whether alloca needs Cray hooks""... $ac_c" 1>&6 -echo "configure:12165: checking whether alloca needs Cray hooks" >&5 +echo "configure:12261: checking whether alloca needs Cray hooks" >&5 cat > conftest.$ac_ext <&6 -echo "configure:12192: checking for $ac_func" >&5 +echo "configure:12288: checking for $ac_func" >&5 cat > conftest.$ac_ext <&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then +if { (eval echo configure:12314: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then rm -rf conftest* eval "ac_cv_func_$ac_func=yes" else @@ -12244,10 +12340,10 @@ fi echo $ac_n "checking stack direction for C alloca""... $ac_c" 1>&6 -echo "configure:12248: checking stack direction for C alloca" >&5 +echo "configure:12344: checking stack direction for C alloca" >&5 cat > conftest.$ac_ext <&5; (eval $ac_link) 2>&5; } && test -s conftest && (./conftest; exit $?) 2>&5 +if { (eval echo configure:12366: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest && (./conftest; exit $?) 2>&5 then ac_cv_c_stack_direction=1 else @@ -12296,15 +12392,15 @@ ac_safe=`echo "vfork.h" | sed 'y%./+-%__p_%'` echo $ac_n "checking for vfork.h""... $ac_c" 1>&6 -echo "configure:12300: checking for vfork.h" >&5 +echo "configure:12396: checking for vfork.h" >&5 cat > conftest.$ac_ext < EOF ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out" -{ (eval echo configure:12308: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; } +{ (eval echo configure:12404: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; } ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"` if test -z "$ac_err"; then rm -rf conftest* @@ -12332,10 +12428,10 @@ fi echo $ac_n "checking for working vfork""... $ac_c" 1>&6 -echo "configure:12336: checking for working vfork" >&5 +echo "configure:12432: checking for working vfork" >&5 cat > conftest.$ac_ext < @@ -12430,7 +12526,7 @@ } } EOF -if { (eval echo configure:12434: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest && (./conftest; exit $?) 2>&5 +if { (eval echo configure:12530: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest && (./conftest; exit $?) 2>&5 then ac_cv_func_vfork_works=yes else @@ -12456,10 +12552,10 @@ echo $ac_n "checking for working strcoll""... $ac_c" 1>&6 -echo "configure:12460: checking for working strcoll" >&5 +echo "configure:12556: checking for working strcoll" >&5 cat > conftest.$ac_ext < main () @@ -12469,7 +12565,7 @@ strcoll ("123", "456") >= 0); } EOF -if { (eval echo configure:12473: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest && (./conftest; exit $?) 2>&5 +if { (eval echo configure:12569: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest && (./conftest; exit $?) 2>&5 then ac_cv_func_strcoll_works=yes else @@ -12497,10 +12593,10 @@ for ac_func in getpgrp do echo $ac_n "checking for $ac_func""... $ac_c" 1>&6 -echo "configure:12501: checking for $ac_func" >&5 +echo "configure:12597: checking for $ac_func" >&5 cat > conftest.$ac_ext <&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then +if { (eval echo configure:12623: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then rm -rf conftest* eval "ac_cv_func_$ac_func=yes" else @@ -12551,10 +12647,10 @@ done echo $ac_n "checking whether getpgrp takes no argument""... $ac_c" 1>&6 -echo "configure:12555: checking whether getpgrp takes no argument" >&5 +echo "configure:12651: checking whether getpgrp takes no argument" >&5 cat > conftest.$ac_ext <&5; (eval $ac_link) 2>&5; } && test -s conftest && (./conftest; exit $?) 2>&5 +if { (eval echo configure:12709: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest && (./conftest; exit $?) 2>&5 then ac_cv_func_getpgrp_void=yes else @@ -12636,10 +12732,10 @@ echo $ac_n "checking for working mmap""... $ac_c" 1>&6 -echo "configure:12640: checking for working mmap" >&5 +echo "configure:12736: checking for working mmap" >&5 case "$opsys" in ultrix* ) have_mmap=no ;; *) cat > conftest.$ac_ext < #include @@ -12672,7 +12768,7 @@ return 1; } EOF -if { (eval echo configure:12676: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest && (./conftest; exit $?) 2>&5 +if { (eval echo configure:12772: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest && (./conftest; exit $?) 2>&5 then have_mmap=yes else @@ -12701,9 +12797,9 @@ if test "$rel_alloc $have_mmap" = "default yes"; then if test "$doug_lea_malloc" = "yes"; then echo $ac_n "checking for M_MMAP_THRESHOLD""... $ac_c" 1>&6 -echo "configure:12705: checking for M_MMAP_THRESHOLD" >&5 +echo "configure:12801: checking for M_MMAP_THRESHOLD" >&5 cat > conftest.$ac_ext < int main() { @@ -12715,7 +12811,7 @@ ; return 0; } EOF -if { (eval echo configure:12719: \"$ac_compile\") 1>&5; (eval $ac_compile) 2>&5; }; then +if { (eval echo configure:12815: \"$ac_compile\") 1>&5; (eval $ac_compile) 2>&5; }; then rm -rf conftest* rel_alloc=no; echo "$ac_t""yes" 1>&6; else @@ -12740,15 +12836,15 @@ ac_safe=`echo "termios.h" | sed 'y%./+-%__p_%'` echo $ac_n "checking for termios.h""... $ac_c" 1>&6 -echo "configure:12744: checking for termios.h" >&5 +echo "configure:12840: checking for termios.h" >&5 cat > conftest.$ac_ext < EOF ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out" -{ (eval echo configure:12752: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; } +{ (eval echo configure:12848: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; } ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"` if test -z "$ac_err"; then rm -rf conftest* @@ -12791,15 +12887,15 @@ echo "$ac_t""no" 1>&6 ac_safe=`echo "termio.h" | sed 'y%./+-%__p_%'` echo $ac_n "checking for termio.h""... $ac_c" 1>&6 -echo "configure:12795: checking for termio.h" >&5 +echo "configure:12891: checking for termio.h" >&5 cat > conftest.$ac_ext < EOF ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out" -{ (eval echo configure:12803: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; } +{ (eval echo configure:12899: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; } ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"` if test -z "$ac_err"; then rm -rf conftest* @@ -12831,10 +12927,10 @@ echo $ac_n "checking for socket""... $ac_c" 1>&6 -echo "configure:12835: checking for socket" >&5 +echo "configure:12931: checking for socket" >&5 cat > conftest.$ac_ext <&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then +if { (eval echo configure:12957: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then rm -rf conftest* eval "ac_cv_func_socket=yes" else @@ -12872,15 +12968,15 @@ echo "$ac_t""yes" 1>&6 ac_safe=`echo "netinet/in.h" | sed 'y%./+-%__p_%'` echo $ac_n "checking for netinet/in.h""... $ac_c" 1>&6 -echo "configure:12876: checking for netinet/in.h" >&5 +echo "configure:12972: checking for netinet/in.h" >&5 cat > conftest.$ac_ext < EOF ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out" -{ (eval echo configure:12884: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; } +{ (eval echo configure:12980: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; } ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"` if test -z "$ac_err"; then rm -rf conftest* @@ -12897,15 +12993,15 @@ echo "$ac_t""yes" 1>&6 ac_safe=`echo "arpa/inet.h" | sed 'y%./+-%__p_%'` echo $ac_n "checking for arpa/inet.h""... $ac_c" 1>&6 -echo "configure:12901: checking for arpa/inet.h" >&5 +echo "configure:12997: checking for arpa/inet.h" >&5 cat > conftest.$ac_ext < EOF ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out" -{ (eval echo configure:12909: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; } +{ (eval echo configure:13005: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; } ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"` if test -z "$ac_err"; then rm -rf conftest* @@ -12930,9 +13026,9 @@ } echo $ac_n "checking "for sun_len member in struct sockaddr_un"""... $ac_c" 1>&6 -echo "configure:12934: checking "for sun_len member in struct sockaddr_un"" >&5 +echo "configure:13030: checking "for sun_len member in struct sockaddr_un"" >&5 cat > conftest.$ac_ext < @@ -12943,7 +13039,7 @@ static struct sockaddr_un x; x.sun_len = 1; ; return 0; } EOF -if { (eval echo configure:12947: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then +if { (eval echo configure:13043: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then rm -rf conftest* echo "$ac_t""yes" 1>&6; { test "$extra_verbose" = "yes" && cat << \EOF Defining HAVE_SOCKADDR_SUN_LEN @@ -12961,9 +13057,9 @@ fi rm -f conftest* echo $ac_n "checking "for ip_mreq struct in netinet/in.h"""... $ac_c" 1>&6 -echo "configure:12965: checking "for ip_mreq struct in netinet/in.h"" >&5 +echo "configure:13061: checking "for ip_mreq struct in netinet/in.h"" >&5 cat > conftest.$ac_ext < @@ -12973,7 +13069,7 @@ static struct ip_mreq x; ; return 0; } EOF -if { (eval echo configure:12977: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then +if { (eval echo configure:13073: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then rm -rf conftest* echo "$ac_t""yes" 1>&6; { test "$extra_verbose" = "yes" && cat << \EOF Defining HAVE_MULTICAST @@ -13004,10 +13100,10 @@ echo $ac_n "checking for msgget""... $ac_c" 1>&6 -echo "configure:13008: checking for msgget" >&5 +echo "configure:13104: checking for msgget" >&5 cat > conftest.$ac_ext <&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then +if { (eval echo configure:13130: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then rm -rf conftest* eval "ac_cv_func_msgget=yes" else @@ -13045,15 +13141,15 @@ echo "$ac_t""yes" 1>&6 ac_safe=`echo "sys/ipc.h" | sed 'y%./+-%__p_%'` echo $ac_n "checking for sys/ipc.h""... $ac_c" 1>&6 -echo "configure:13049: checking for sys/ipc.h" >&5 +echo "configure:13145: checking for sys/ipc.h" >&5 cat > conftest.$ac_ext < EOF ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out" -{ (eval echo configure:13057: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; } +{ (eval echo configure:13153: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; } ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"` if test -z "$ac_err"; then rm -rf conftest* @@ -13070,15 +13166,15 @@ echo "$ac_t""yes" 1>&6 ac_safe=`echo "sys/msg.h" | sed 'y%./+-%__p_%'` echo $ac_n "checking for sys/msg.h""... $ac_c" 1>&6 -echo "configure:13074: checking for sys/msg.h" >&5 +echo "configure:13170: checking for sys/msg.h" >&5 cat > conftest.$ac_ext < EOF ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out" -{ (eval echo configure:13082: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; } +{ (eval echo configure:13178: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; } ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"` if test -z "$ac_err"; then rm -rf conftest* @@ -13116,15 +13212,15 @@ ac_safe=`echo "dirent.h" | sed 'y%./+-%__p_%'` echo $ac_n "checking for dirent.h""... $ac_c" 1>&6 -echo "configure:13120: checking for dirent.h" >&5 +echo "configure:13216: checking for dirent.h" >&5 cat > conftest.$ac_ext < EOF ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out" -{ (eval echo configure:13128: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; } +{ (eval echo configure:13224: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; } ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"` if test -z "$ac_err"; then rm -rf conftest* @@ -13151,15 +13247,15 @@ echo "$ac_t""no" 1>&6 ac_safe=`echo "sys/dir.h" | sed 'y%./+-%__p_%'` echo $ac_n "checking for sys/dir.h""... $ac_c" 1>&6 -echo "configure:13155: checking for sys/dir.h" >&5 +echo "configure:13251: checking for sys/dir.h" >&5 cat > conftest.$ac_ext < EOF ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out" -{ (eval echo configure:13163: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; } +{ (eval echo configure:13259: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; } ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"` if test -z "$ac_err"; then rm -rf conftest* @@ -13192,15 +13288,15 @@ ac_safe=`echo "nlist.h" | sed 'y%./+-%__p_%'` echo $ac_n "checking for nlist.h""... $ac_c" 1>&6 -echo "configure:13196: checking for nlist.h" >&5 +echo "configure:13292: checking for nlist.h" >&5 cat > conftest.$ac_ext < EOF ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out" -{ (eval echo configure:13204: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; } +{ (eval echo configure:13300: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; } ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"` if test -z "$ac_err"; then rm -rf conftest* @@ -13230,22 +13326,22 @@ echo "checking "for sound support"" 1>&6 -echo "configure:13234: checking "for sound support"" >&5 +echo "configure:13330: checking "for sound support"" >&5 test -z "$with_native_sound" -a -n "$native_sound_lib" && with_native_sound=yes if test "$with_native_sound" != "no"; then if test -n "$native_sound_lib"; then ac_safe=`echo "multimedia/audio_device.h" | sed 'y%./+-%__p_%'` echo $ac_n "checking for multimedia/audio_device.h""... $ac_c" 1>&6 -echo "configure:13241: checking for multimedia/audio_device.h" >&5 +echo "configure:13337: checking for multimedia/audio_device.h" >&5 cat > conftest.$ac_ext < EOF ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out" -{ (eval echo configure:13249: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; } +{ (eval echo configure:13345: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; } ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"` if test -z "$ac_err"; then rm -rf conftest* @@ -13301,12 +13397,12 @@ if test -z "$native_sound_lib"; then echo $ac_n "checking for ALopenport in -laudio""... $ac_c" 1>&6 -echo "configure:13305: checking for ALopenport in -laudio" >&5 +echo "configure:13401: checking for ALopenport in -laudio" >&5 ac_lib_var=`echo audio'_'ALopenport | sed 'y%./+-%__p_%'` xe_check_libs=" -laudio " cat > conftest.$ac_ext <&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then +if { (eval echo configure:13417: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then rm -rf conftest* eval "ac_cv_lib_$ac_lib_var=yes" else @@ -13348,12 +13444,12 @@ if test -z "$native_sound_lib"; then echo $ac_n "checking for AOpenAudio in -lAlib""... $ac_c" 1>&6 -echo "configure:13352: checking for AOpenAudio in -lAlib" >&5 +echo "configure:13448: checking for AOpenAudio in -lAlib" >&5 ac_lib_var=`echo Alib'_'AOpenAudio | sed 'y%./+-%__p_%'` xe_check_libs=" -lAlib " cat > conftest.$ac_ext <&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then +if { (eval echo configure:13464: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then rm -rf conftest* eval "ac_cv_lib_$ac_lib_var=yes" else @@ -13409,15 +13505,15 @@ for dir in "machine" "sys" "linux"; do ac_safe=`echo "${dir}/soundcard.h" | sed 'y%./+-%__p_%'` echo $ac_n "checking for ${dir}/soundcard.h""... $ac_c" 1>&6 -echo "configure:13413: checking for ${dir}/soundcard.h" >&5 +echo "configure:13509: checking for ${dir}/soundcard.h" >&5 cat > conftest.$ac_ext < EOF ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out" -{ (eval echo configure:13421: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; } +{ (eval echo configure:13517: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; } ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"` if test -z "$ac_err"; then rm -rf conftest* @@ -13471,15 +13567,15 @@ if test "$with_nas_sound" != "no"; then ac_safe=`echo "audio/audiolib.h" | sed 'y%./+-%__p_%'` echo $ac_n "checking for audio/audiolib.h""... $ac_c" 1>&6 -echo "configure:13475: checking for audio/audiolib.h" >&5 +echo "configure:13571: checking for audio/audiolib.h" >&5 cat > conftest.$ac_ext < EOF ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out" -{ (eval echo configure:13483: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; } +{ (eval echo configure:13579: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; } ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"` if test -z "$ac_err"; then rm -rf conftest* @@ -13497,12 +13593,12 @@ echo $ac_n "checking for AuOpenServer in -laudio""... $ac_c" 1>&6 -echo "configure:13501: checking for AuOpenServer in -laudio" >&5 +echo "configure:13597: checking for AuOpenServer in -laudio" >&5 ac_lib_var=`echo audio'_'AuOpenServer | sed 'y%./+-%__p_%'` xe_check_libs=" -laudio " cat > conftest.$ac_ext <&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then +if { (eval echo configure:13613: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then rm -rf conftest* eval "ac_cv_lib_$ac_lib_var=yes" else @@ -13552,7 +13648,7 @@ fi libs_x="-laudio $libs_x" && if test "$extra_verbose" = "yes"; then echo " Prepending \"-laudio\" to \$libs_x"; fi cat > conftest.$ac_ext < EOF @@ -13583,7 +13679,7 @@ # Extract the first word of "esd-config", so it can be a program name with args. set dummy esd-config; ac_word=$2 echo $ac_n "checking for $ac_word""... $ac_c" 1>&6 -echo "configure:13587: checking for $ac_word" >&5 +echo "configure:13683: checking for $ac_word" >&5 if test -n "$have_esd_config"; then ac_cv_prog_have_esd_config="$have_esd_config" # Let the user override the test. @@ -13612,10 +13708,10 @@ c_switch_site="$c_switch_site `esd-config --cflags`" && if test "$extra_verbose" = "yes"; then echo " Appending \"`esd-config --cflags`\" to \$c_switch_site"; fi LIBS="`esd-config --libs` $LIBS" && if test "$extra_verbose" = "yes"; then echo " Prepending \"`esd-config --libs`\" to \$LIBS"; fi echo $ac_n "checking for esd_play_stream""... $ac_c" 1>&6 -echo "configure:13616: checking for esd_play_stream" >&5 +echo "configure:13712: checking for esd_play_stream" >&5 cat > conftest.$ac_ext <&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then +if { (eval echo configure:13738: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then rm -rf conftest* eval "ac_cv_func_esd_play_stream=yes" else @@ -13689,7 +13785,7 @@ if test "$with_tty" = "yes" ; then echo "checking for TTY-related features" 1>&6 -echo "configure:13693: checking for TTY-related features" >&5 +echo "configure:13789: checking for TTY-related features" >&5 { test "$extra_verbose" = "yes" && cat << \EOF Defining HAVE_TTY EOF @@ -13705,12 +13801,12 @@ if test -z "$with_ncurses"; then echo $ac_n "checking for tgetent in -lncurses""... $ac_c" 1>&6 -echo "configure:13709: checking for tgetent in -lncurses" >&5 +echo "configure:13805: checking for tgetent in -lncurses" >&5 ac_lib_var=`echo ncurses'_'tgetent | sed 'y%./+-%__p_%'` xe_check_libs=" -lncurses " cat > conftest.$ac_ext <&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then +if { (eval echo configure:13821: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then rm -rf conftest* eval "ac_cv_lib_$ac_lib_var=yes" else @@ -13754,15 +13850,15 @@ ac_safe=`echo "ncurses/curses.h" | sed 'y%./+-%__p_%'` echo $ac_n "checking for ncurses/curses.h""... $ac_c" 1>&6 -echo "configure:13758: checking for ncurses/curses.h" >&5 +echo "configure:13854: checking for ncurses/curses.h" >&5 cat > conftest.$ac_ext < EOF ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out" -{ (eval echo configure:13766: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; } +{ (eval echo configure:13862: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; } ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"` if test -z "$ac_err"; then rm -rf conftest* @@ -13784,15 +13880,15 @@ ac_safe=`echo "ncurses/term.h" | sed 'y%./+-%__p_%'` echo $ac_n "checking for ncurses/term.h""... $ac_c" 1>&6 -echo "configure:13788: checking for ncurses/term.h" >&5 +echo "configure:13884: checking for ncurses/term.h" >&5 cat > conftest.$ac_ext < EOF ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out" -{ (eval echo configure:13796: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; } +{ (eval echo configure:13892: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; } ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"` if test -z "$ac_err"; then rm -rf conftest* @@ -13822,15 +13918,15 @@ c_switch_site="$c_switch_site -I/usr/include/ncurses" ac_safe=`echo "ncurses/curses.h" | sed 'y%./+-%__p_%'` echo $ac_n "checking for ncurses/curses.h""... $ac_c" 1>&6 -echo "configure:13826: checking for ncurses/curses.h" >&5 +echo "configure:13922: checking for ncurses/curses.h" >&5 cat > conftest.$ac_ext < EOF ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out" -{ (eval echo configure:13834: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; } +{ (eval echo configure:13930: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; } ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"` if test -z "$ac_err"; then rm -rf conftest* @@ -13865,12 +13961,12 @@ for lib in curses termlib termcap; do echo $ac_n "checking for tgetent in -l$lib""... $ac_c" 1>&6 -echo "configure:13869: checking for tgetent in -l$lib" >&5 +echo "configure:13965: checking for tgetent in -l$lib" >&5 ac_lib_var=`echo $lib'_'tgetent | sed 'y%./+-%__p_%'` xe_check_libs=" -l$lib " cat > conftest.$ac_ext <&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then +if { (eval echo configure:13981: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then rm -rf conftest* eval "ac_cv_lib_$ac_lib_var=yes" else @@ -13906,12 +14002,12 @@ else if test -n "$libs_termcap" -a "$opsys" = "openbsd"; then echo $ac_n "checking for tgoto in -ltermcap""... $ac_c" 1>&6 -echo "configure:13910: checking for tgoto in -ltermcap" >&5 +echo "configure:14006: checking for tgoto in -ltermcap" >&5 ac_lib_var=`echo termcap'_'tgoto | sed 'y%./+-%__p_%'` xe_check_libs=" -ltermcap " cat > conftest.$ac_ext <&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then +if { (eval echo configure:14022: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then rm -rf conftest* eval "ac_cv_lib_$ac_lib_var=yes" else @@ -13967,12 +14063,12 @@ else echo $ac_n "checking for tgetent in -lcurses""... $ac_c" 1>&6 -echo "configure:13971: checking for tgetent in -lcurses" >&5 +echo "configure:14067: checking for tgetent in -lcurses" >&5 ac_lib_var=`echo curses'_'tgetent | sed 'y%./+-%__p_%'` xe_check_libs=" -lcurses " cat > conftest.$ac_ext <&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then +if { (eval echo configure:14083: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then rm -rf conftest* eval "ac_cv_lib_$ac_lib_var=yes" else @@ -14001,12 +14097,12 @@ else echo "$ac_t""no" 1>&6 echo $ac_n "checking for tgetent in -ltermcap""... $ac_c" 1>&6 -echo "configure:14005: checking for tgetent in -ltermcap" >&5 +echo "configure:14101: checking for tgetent in -ltermcap" >&5 ac_lib_var=`echo termcap'_'tgetent | sed 'y%./+-%__p_%'` xe_check_libs=" -ltermcap " cat > conftest.$ac_ext <&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then +if { (eval echo configure:14117: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then rm -rf conftest* eval "ac_cv_lib_$ac_lib_var=yes" else @@ -14066,15 +14162,15 @@ if test "$with_gpm" != "no"; then ac_safe=`echo "gpm.h" | sed 'y%./+-%__p_%'` echo $ac_n "checking for gpm.h""... $ac_c" 1>&6 -echo "configure:14070: checking for gpm.h" >&5 +echo "configure:14166: checking for gpm.h" >&5 cat > conftest.$ac_ext < EOF ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out" -{ (eval echo configure:14078: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; } +{ (eval echo configure:14174: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; } ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"` if test -z "$ac_err"; then rm -rf conftest* @@ -14092,12 +14188,12 @@ echo $ac_n "checking for Gpm_Open in -lgpm""... $ac_c" 1>&6 -echo "configure:14096: checking for Gpm_Open in -lgpm" >&5 +echo "configure:14192: checking for Gpm_Open in -lgpm" >&5 ac_lib_var=`echo gpm'_'Gpm_Open | sed 'y%./+-%__p_%'` xe_check_libs=" -lgpm " cat > conftest.$ac_ext <&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then +if { (eval echo configure:14208: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then rm -rf conftest* eval "ac_cv_lib_$ac_lib_var=yes" else @@ -14167,20 +14263,20 @@ test "$with_database_gdbm $with_database_dbm $with_database_berkdb" \ != "no no no" && echo "checking for database support" 1>&6 -echo "configure:14171: checking for database support" >&5 +echo "configure:14267: checking for database support" >&5 if test "$with_database_gdbm $with_database_dbm" != "no no"; then ac_safe=`echo "ndbm.h" | sed 'y%./+-%__p_%'` echo $ac_n "checking for ndbm.h""... $ac_c" 1>&6 -echo "configure:14176: checking for ndbm.h" >&5 +echo "configure:14272: checking for ndbm.h" >&5 cat > conftest.$ac_ext < EOF ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out" -{ (eval echo configure:14184: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; } +{ (eval echo configure:14280: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; } ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"` if test -z "$ac_err"; then rm -rf conftest* @@ -14210,12 +14306,12 @@ if test "$with_database_gdbm" != "no"; then echo $ac_n "checking for dbm_open in -lgdbm""... $ac_c" 1>&6 -echo "configure:14214: checking for dbm_open in -lgdbm" >&5 +echo "configure:14310: checking for dbm_open in -lgdbm" >&5 ac_lib_var=`echo gdbm'_'dbm_open | sed 'y%./+-%__p_%'` xe_check_libs=" -lgdbm " cat > conftest.$ac_ext <&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then +if { (eval echo configure:14326: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then rm -rf conftest* eval "ac_cv_lib_$ac_lib_var=yes" else @@ -14254,10 +14350,10 @@ if test "$with_database_dbm" != "no"; then echo $ac_n "checking for dbm_open""... $ac_c" 1>&6 -echo "configure:14258: checking for dbm_open" >&5 +echo "configure:14354: checking for dbm_open" >&5 cat > conftest.$ac_ext <&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then +if { (eval echo configure:14380: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then rm -rf conftest* eval "ac_cv_func_dbm_open=yes" else @@ -14299,12 +14395,12 @@ echo $ac_n "checking for dbm_open in -ldbm""... $ac_c" 1>&6 -echo "configure:14303: checking for dbm_open in -ldbm" >&5 +echo "configure:14399: checking for dbm_open in -ldbm" >&5 ac_lib_var=`echo dbm'_'dbm_open | sed 'y%./+-%__p_%'` xe_check_libs=" -ldbm " cat > conftest.$ac_ext <&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then +if { (eval echo configure:14415: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then rm -rf conftest* eval "ac_cv_lib_$ac_lib_var=yes" else @@ -14355,10 +14451,10 @@ echo $ac_n "checking for u_int8_t""... $ac_c" 1>&6 -echo "configure:14359: checking for u_int8_t" >&5 +echo "configure:14455: checking for u_int8_t" >&5 cat > conftest.$ac_ext < #if STDC_HEADERS @@ -14399,10 +14495,10 @@ fi echo $ac_n "checking for u_int16_t""... $ac_c" 1>&6 -echo "configure:14403: checking for u_int16_t" >&5 +echo "configure:14499: checking for u_int16_t" >&5 cat > conftest.$ac_ext < #if STDC_HEADERS @@ -14443,10 +14539,10 @@ fi echo $ac_n "checking for u_int32_t""... $ac_c" 1>&6 -echo "configure:14447: checking for u_int32_t" >&5 +echo "configure:14543: checking for u_int32_t" >&5 cat > conftest.$ac_ext < #if STDC_HEADERS @@ -14487,10 +14583,10 @@ fi echo $ac_n "checking for u_int64_t""... $ac_c" 1>&6 -echo "configure:14491: checking for u_int64_t" >&5 +echo "configure:14587: checking for u_int64_t" >&5 cat > conftest.$ac_ext < #if STDC_HEADERS @@ -14533,12 +14629,12 @@ if test "$with_database_berkdb" != "no"; then echo $ac_n "checking for Berkeley db.h""... $ac_c" 1>&6 -echo "configure:14537: checking for Berkeley db.h" >&5 +echo "configure:14633: checking for Berkeley db.h" >&5 for header in "db/db.h" "db.h"; do case "$opsys" in *freebsd*) cat > conftest.$ac_ext < @@ -14554,7 +14650,7 @@ ; return 0; } EOF -if { (eval echo configure:14558: \"$ac_compile\") 1>&5; (eval $ac_compile) 2>&5; }; then +if { (eval echo configure:14654: \"$ac_compile\") 1>&5; (eval $ac_compile) 2>&5; }; then rm -rf conftest* db_h_file="$header"; break else @@ -14565,7 +14661,7 @@ ;; *) cat > conftest.$ac_ext < @@ -14595,7 +14691,7 @@ ; return 0; } EOF -if { (eval echo configure:14599: \"$ac_compile\") 1>&5; (eval $ac_compile) 2>&5; }; then +if { (eval echo configure:14695: \"$ac_compile\") 1>&5; (eval $ac_compile) 2>&5; }; then rm -rf conftest* db_h_file="$header"; break else @@ -14613,9 +14709,9 @@ if test "$with_database_berkdb" != "no"; then echo $ac_n "checking for Berkeley DB version""... $ac_c" 1>&6 -echo "configure:14617: checking for Berkeley DB version" >&5 +echo "configure:14713: checking for Berkeley DB version" >&5 cat > conftest.$ac_ext < #if DB_VERSION_MAJOR > 1 @@ -14627,7 +14723,7 @@ egrep "yes" >/dev/null 2>&1; then rm -rf conftest* cat > conftest.$ac_ext < #if DB_VERSION_MAJOR > 2 @@ -14654,10 +14750,10 @@ rm -f conftest* echo $ac_n "checking for $dbfunc""... $ac_c" 1>&6 -echo "configure:14658: checking for $dbfunc" >&5 +echo "configure:14754: checking for $dbfunc" >&5 cat > conftest.$ac_ext <&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then +if { (eval echo configure:14780: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then rm -rf conftest* eval "ac_cv_func_$dbfunc=yes" else @@ -14699,12 +14795,12 @@ echo $ac_n "checking for $dbfunc in -ldb""... $ac_c" 1>&6 -echo "configure:14703: checking for $dbfunc in -ldb" >&5 +echo "configure:14799: checking for $dbfunc in -ldb" >&5 ac_lib_var=`echo db'_'$dbfunc | sed 'y%./+-%__p_%'` xe_check_libs=" -ldb " cat > conftest.$ac_ext <&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then +if { (eval echo configure:14815: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then rm -rf conftest* eval "ac_cv_lib_$ac_lib_var=yes" else @@ -14779,12 +14875,12 @@ if test "$with_socks" = "yes"; then echo $ac_n "checking for SOCKSinit in -lsocks""... $ac_c" 1>&6 -echo "configure:14783: checking for SOCKSinit in -lsocks" >&5 +echo "configure:14879: checking for SOCKSinit in -lsocks" >&5 ac_lib_var=`echo socks'_'SOCKSinit | sed 'y%./+-%__p_%'` xe_check_libs=" -lsocks " cat > conftest.$ac_ext <&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then +if { (eval echo configure:14895: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then rm -rf conftest* eval "ac_cv_lib_$ac_lib_var=yes" else @@ -14850,7 +14946,7 @@ if test "$with_modules" != "no"; then echo "checking for module support" 1>&6 -echo "configure:14854: checking for module support" >&5 +echo "configure:14950: checking for module support" >&5 if test "$with_msw" = "yes"; then have_dl=yes; @@ -14866,15 +14962,15 @@ ;; *) ac_safe=`echo "dlfcn.h" | sed 'y%./+-%__p_%'` echo $ac_n "checking for dlfcn.h""... $ac_c" 1>&6 -echo "configure:14870: checking for dlfcn.h" >&5 +echo "configure:14966: checking for dlfcn.h" >&5 cat > conftest.$ac_ext < EOF ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out" -{ (eval echo configure:14878: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; } +{ (eval echo configure:14974: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; } ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"` if test -z "$ac_err"; then rm -rf conftest* @@ -14891,16 +14987,16 @@ echo "$ac_t""yes" 1>&6 echo $ac_n "checking for dlopen in -lc""... $ac_c" 1>&6 -echo "configure:14895: checking for dlopen in -lc" >&5 +echo "configure:14991: checking for dlopen in -lc" >&5 cat > conftest.$ac_ext < int main() { dlopen ("", 0); ; return 0; } EOF -if { (eval echo configure:14904: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then +if { (eval echo configure:15000: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then rm -rf conftest* have_dl=yes else @@ -14909,18 +15005,18 @@ rm -rf conftest* echo $ac_n "checking for dlopen in -ldl""... $ac_c" 1>&6 -echo "configure:14913: checking for dlopen in -ldl" >&5 +echo "configure:15009: checking for dlopen in -ldl" >&5 ac_save_LIBS="$LIBS" LIBS="-ldl $LIBS" cat > conftest.$ac_ext < int main() { dlopen ("", 0); ; return 0; } EOF -if { (eval echo configure:14924: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then +if { (eval echo configure:15020: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then rm -rf conftest* have_dl=yes else @@ -14949,12 +15045,12 @@ else echo $ac_n "checking for shl_load in -ldld""... $ac_c" 1>&6 -echo "configure:14953: checking for shl_load in -ldld" >&5 +echo "configure:15049: checking for shl_load in -ldld" >&5 ac_lib_var=`echo dld'_'shl_load | sed 'y%./+-%__p_%'` xe_check_libs=" -ldld " cat > conftest.$ac_ext <&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then +if { (eval echo configure:15065: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then rm -rf conftest* eval "ac_cv_lib_$ac_lib_var=yes" else @@ -14992,12 +15088,12 @@ echo "$ac_t""no" 1>&6 echo $ac_n "checking for dld_init in -ldld""... $ac_c" 1>&6 -echo "configure:14996: checking for dld_init in -ldld" >&5 +echo "configure:15092: checking for dld_init in -ldld" >&5 ac_lib_var=`echo dld'_'dld_init | sed 'y%./+-%__p_%'` xe_check_libs=" -ldld " cat > conftest.$ac_ext <&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then +if { (eval echo configure:15108: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then rm -rf conftest* eval "ac_cv_lib_$ac_lib_var=yes" else @@ -15055,7 +15151,7 @@ xealias=$internal_configuration echo "checking how to build dynamic libraries for ${xehost}" 1>&6 -echo "configure:15059: checking how to build dynamic libraries for ${xehost}" >&5 +echo "configure:15155: checking how to build dynamic libraries for ${xehost}" >&5 # Transform *-*-linux* to *-*-linux-gnu*, to support old configure scripts. case "$xehost" in *-*-linux-gnu*) ;; @@ -15083,9 +15179,9 @@ XEGCC=yes else echo $ac_n "checking checking whether we are using GNU C""... $ac_c" 1>&6 -echo "configure:15087: checking checking whether we are using GNU C" >&5 +echo "configure:15183: checking checking whether we are using GNU C" >&5 cat > conftest.$ac_ext <&6 -echo "configure:15111: checking how to produce PIC code" >&5 +echo "configure:15207: checking how to produce PIC code" >&5 wl= can_build_shared=yes @@ -15208,18 +15304,18 @@ # Check to make sure the dll_cflags actually works. echo $ac_n "checking if PIC flag ${dll_cflags} really works""... $ac_c" 1>&6 -echo "configure:15212: checking if PIC flag ${dll_cflags} really works" >&5 +echo "configure:15308: checking if PIC flag ${dll_cflags} really works" >&5 save_CFLAGS="$CFLAGS" CFLAGS="$CFLAGS $dll_cflags -DPIC" cat > conftest.$ac_ext <&5; (eval $ac_compile) 2>&5; }; then +if { (eval echo configure:15319: \"$ac_compile\") 1>&5; (eval $ac_compile) 2>&5; }; then rm -rf conftest* # On HP-UX, the stripped-down bundled CC doesn't accept +Z, but also @@ -15250,7 +15346,7 @@ xldf= xcldf= echo $ac_n "checking if C compiler can produce shared libraries""... $ac_c" 1>&6 -echo "configure:15254: checking if C compiler can produce shared libraries" >&5 +echo "configure:15350: checking if C compiler can produce shared libraries" >&5 if test "$XEGCC" = yes -o "$__ICC" = yes; then xcldf="-shared" xldf="-shared" @@ -15301,14 +15397,14 @@ xe_libs= ac_link='${CC-cc} -o conftest $CFLAGS '"$xe_cppflags $xe_ldflags"' conftest.$ac_ext '"$xe_libs"' 1>&5' cat > conftest.$ac_ext <&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then +if { (eval echo configure:15408: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then rm -rf conftest* cc_produces_so=yes else @@ -15333,7 +15429,7 @@ if test "$XEGCC" = yes; then # Check if gcc -print-prog-name=ld gives a path. echo $ac_n "checking for ld used by GCC""... $ac_c" 1>&6 -echo "configure:15337: checking for ld used by GCC" >&5 +echo "configure:15433: checking for ld used by GCC" >&5 ac_prog=`($CC -print-prog-name=ld) 2>&5` case "$ac_prog" in # Accept absolute paths. @@ -15359,7 +15455,7 @@ esac else echo $ac_n "checking for GNU ld""... $ac_c" 1>&6 -echo "configure:15363: checking for GNU ld" >&5 +echo "configure:15459: checking for GNU ld" >&5 fi if test -z "$LTLD"; then @@ -15397,7 +15493,7 @@ # Check to see if it really is or isn't GNU ld. echo $ac_n "checking if the linker is GNU ld""... $ac_c" 1>&6 -echo "configure:15401: checking if the linker is GNU ld" >&5 +echo "configure:15497: checking if the linker is GNU ld" >&5 # I'd rather use --version here, but apparently some GNU ld's only accept -v. if $LTLD -v 2>&1 &5; then xe_gnu_ld=yes @@ -15425,7 +15521,7 @@ # OK - only NOW do we futz about with ld. # See if the linker supports building shared libraries. echo $ac_n "checking whether the linker supports shared libraries""... $ac_c" 1>&6 -echo "configure:15429: checking whether the linker supports shared libraries" >&5 +echo "configure:15525: checking whether the linker supports shared libraries" >&5 dll_ld=$CC dll_ldflags=$LDFLAGS ld_shlibs=yes @@ -15636,10 +15732,10 @@ for ac_func in dlerror _dlerror do echo $ac_n "checking for $ac_func""... $ac_c" 1>&6 -echo "configure:15640: checking for $ac_func" >&5 +echo "configure:15736: checking for $ac_func" >&5 cat > conftest.$ac_ext <&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then +if { (eval echo configure:15762: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then rm -rf conftest* eval "ac_cv_func_$ac_func=yes" else @@ -15701,11 +15797,11 @@ fi cat > conftest.$ac_ext <&5; (eval $ac_link) 2>&5; } && test -s conftest && (./conftest; exit $?) 2>&5 +if { (eval echo configure:15805: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest && (./conftest; exit $?) 2>&5 then : else diff -u -r -N xemacs-21.4.18/configure.in xemacs-21.4.19/configure.in --- xemacs-21.4.18/configure.in 2005-11-30 18:58:31.000000000 -0500 +++ xemacs-21.4.19/configure.in 2005-12-23 19:48:14.000000000 -0500 @@ -3215,6 +3215,7 @@ echo "Setting ldap_libs to $ldap_libs"],dnl [AC_CHECK_LIB(ldap, ldap_open,dnl [with_ldap=yes],dnl +dnl If logic of setting these vars change, change it the same way below. [ldap_needs_lber=yes ldap_other_libs=-llber dnl This requires `AC_CACHE_VAL' (which is called by `AC_CHECK_LIB') dnl to be redefined to ignore cached (shell variable) value, as it is @@ -3236,6 +3237,55 @@ $ldap_other_libs)],dnl $ldap_other_libs)],dnl $ldap_other_libs)]) + if test yes = "$with_ldap" -a yes != "$ldap_needs_lber";then +dnl Need this check since `LDAP_OPT_ON' is (currently) used only with +dnl `ldap_set_option', and the latter may not exist at all, for which +dnl is testing later. So `LDAP_OPT_ON' is not necessarily defined. + AC_CACHE_CHECK([for LDAP_OPT_ON definition],xe_cv_have_LDAP_OPT_ON, + [AC_TRY_COMPILE( +[#include +#include +#ifdef LDAP_OPT_ON +/* Relying on const defined by ac_c_const (upper case). */ +const void *const v = LDAP_OPT_ON; +#else /* !defined (LDAP_OPT_ON) */ +choke me +#endif /* !defined (LDAP_OPT_ON) */],[], + [xe_cv_have_LDAP_OPT_ON=yes], + [xe_cv_have_LDAP_OPT_ON=no])]) + if test yes = "$xe_cv_have_LDAP_OPT_ON";then + AC_CACHE_CHECK([LDAP_OPT_ON linking], + xe_cv_LDAP_OPT_ON_links, + [xe_save_LIBS="$LIBS" + LIBS="-lldap $LIBS" +AC_TRY_LINK( +[#include +#include +const void *const v = LDAP_OPT_ON;],[], + xe_cv_LDAP_OPT_ON_links=yes, + xe_cv_LDAP_OPT_ON_links=no) + LIBS="$xe_save_LIBS"]) +dnl In some openldap installations other `ldap_*' functions link with +dnl `-lldap' alone, but `LDAP_OPT_ON' requires `-llber'. + if test yes != "$xe_cv_LDAP_OPT_ON_links";then + ldap_needs_lber=yes ldap_other_libs=-llber + AC_CACHE_CHECK([LDAP_OPT_ON linking with -llber], + xe_cv_LDAP_OPT_ON_links_w_lber, + [xe_save_LIBS="$LIBS" + LIBS="-lldap $ldap_other_libs $LIBS" +AC_TRY_LINK( +[#include +#include +const void *const v = LDAP_OPT_ON;],[], + xe_cv_LDAP_OPT_ON_links_w_lber=yes, + xe_cv_LDAP_OPT_ON_links_w_lber=no) + LIBS="$xe_save_LIBS"]) + if test yes != "$xe_cv_LDAP_OPT_ON_links_w_lber";then + with_ldap=no + fi + fi + fi + fi if test yes = "$with_ldap";then if test yes = "$ldap_needs_des";then XE_PREPEND(-ldes, ldap_libs) diff -u -r -N xemacs-21.4.18/etc/NEWS xemacs-21.4.19/etc/NEWS --- xemacs-21.4.18/etc/NEWS 2005-11-30 18:59:18.000000000 -0500 +++ xemacs-21.4.19/etc/NEWS 2005-12-23 19:52:26.000000000 -0500 @@ -33,7 +33,10 @@ ======================== ** Summary of user-visible changes: - + -- Motif is now deprecated on linux and cygwin. + -- On UNIX and linux, '--with-widgets=no' is now the default. If + you want buffer tabs or the progress bar, you must run configure + with the option '--with-widgets=lucid' or a different toolkit. -- PUI related changes (Package User Interface) - A minor rearrangement of the "Tools -> Packages" menu. - Only a single package download site can be selected. @@ -118,6 +121,7 @@ - Python now supported. - New file extensions recognized: .ss, .pdb, .psw. -- Fixed ldap libraries configuration. + -- Fixed `LDAP_OPT_ON' libraries configuration. ** The delete key now deletes forward by default. @@ -605,19 +609,28 @@ It used to fail when `-lldap' requires `-llber'. Introduced in upstream `configure.in' revision 1.151.2.31 (2005/01/31 02:54:47 +0). +*** Fixed `LDAP_OPT_ON' libraries configuration. + +The original fix of local `configure.in' revision 1.19 (2004/12/19 +21:10:02 +0) introduced lossage on another class of systems. In some +openldap versions `ldap_*' functions may link successfully without +`-lber', but compiling and linking program with `LDAP_OPT_ON' may +require `-lber'. When configuring ldap libraries, check for such +systems, and in a cleaner way than in upstream. + * Lisp and internal changes in XEmacs 21.4 ========================================== -** A new portable dumper is available for beta testing. +** A new portable dumper is available. Olivier Galibert has written a portable dumper for XEmacs, based on -initial work by Kyle Jones. To perform even the most basic editor, -XEmacs requires some amount of Lisp code to be loaded. To avoid -repeating the expensive loading process at every startup, XEmacs is -built in a special way. Its C sources link into an executable called -`temacs', which loads the bootstrap Lisp code and uses a special -"unexec" call to dump the resulting memory image into a proper +initial work by Kyle Jones. To perform even the most basic editor +functions, XEmacs requires some amount of Lisp code to be loaded. To +avoid repeating the expensive loading process at every startup, XEmacs +is built in a special way. Its C sources link into an executable +called `temacs', which loads the bootstrap Lisp code and uses a +special "unexec" call to dump the resulting memory image into a proper `xemacs' executable on disk. The unexec() process is hard to implement correctly and makes XEmacs very hard to port to new operating systems, or even to new releases of old systems. @@ -629,11 +642,10 @@ to the initialized data. In that scheme, there is no difference between `temacs' and `xemacs'. -Unfortunately, the portable dumper has not been completely finished -for this release, and will not be used by default. However, if you -wish to experiment with it, or if you need to compile XEmacs on a new -and unsupported platform, you can test it by configuring XEmacs with -`--pdump' flag. +The portable dumper will not be used by default in this release, +however, if you wish to experiment with it, or if you need to compile +XEmacs on a new and unsupported platform, you can test it by +configuring XEmacs using the `--pdump' flag. ** Much effort has been invested to make XEmacs Lisp faster: diff -u -r -N xemacs-21.4.18/etc/OXYMORONS xemacs-21.4.19/etc/OXYMORONS --- xemacs-21.4.18/etc/OXYMORONS 2005-02-14 21:10:35.000000000 -0500 +++ xemacs-21.4.19/etc/OXYMORONS 2005-12-03 15:51:41.000000000 -0500 @@ -33,14 +33,15 @@ 21.4.15: Security Through Obscurity 21.4.16: Corporate Culture 21.4.17: Jumbo Shrimp -21.4.18: Constant Variable -21.4.19: Double Solitaire -21.4.20: Educational Television -21.4.21: Instant Classic -21.4.22: Moral Majority -21.4.23: Standard C -21.4.24: Too Much Mozart -21.4.25: Working Vacation +21.4.18: Social Property +21.4.19: Constant Variable +21.4.20: Double Solitaire +21.4.21: Educational Television +21.4.22: Instant Classic +21.4.23: Moral Majority +21.4.24: Standard C +21.4.25: Too Much Mozart +21.4.26: Working Vacation diff -u -r -N xemacs-21.4.18/etc/PACKAGES xemacs-21.4.19/etc/PACKAGES --- xemacs-21.4.18/etc/PACKAGES 2005-11-24 21:01:46.000000000 -0500 +++ xemacs-21.4.19/etc/PACKAGES 2005-12-04 20:46:55.000000000 -0500 @@ -345,7 +345,7 @@ tailored. *** xetla -(setq mm-coding-system-priorities '(iso-8859-1 iso-8859-15 utf-8)) +Frontend to GNU/arch (tla). *** xlib Emacs interface to X server. diff -u -r -N xemacs-21.4.18/etc/package-index.LATEST.gpg xemacs-21.4.19/etc/package-index.LATEST.gpg --- xemacs-21.4.18/etc/package-index.LATEST.gpg 2004-01-26 22:56:23.000000000 -0500 +++ xemacs-21.4.19/etc/package-index.LATEST.gpg 2006-01-28 17:47:11.000000000 -0500 @@ -4,21 +4,190 @@ ;; Package Index file -- Do not edit manually. ;;;@@@ (package-get-update-base-entry (quote -(general-docs +(xetla (standards-version 1.1 version "1.01" + author-version "steve@eicq.org--2005/xetla--main--1.1--version-0" + date "2005-12-29" + build-date "2005-12-29" + maintainer "Steve Youngs " + distribution xemacs + priority low + category "standard" + dump nil + description "(S)XEmacs Frontend to GNU/arch (tla)." + filename "xetla-1.01-pkg.tar.gz" + md5sum "45c66a4429f53553fda1030e4f0d1e85" + size 294912 + provides (ewoc xetla-browse xetla-core + xetla-defs xetla-tips xetla-version xetla) + requires (ediff xemacs-base jde mail-lib dired prog-modes) + type regular +)) +)) +;;;@@@ +(package-get-update-base-entry (quote +(re-builder + (standards-version 1.1 + version "1.05" + author-version "1.20" + date "2005-09-12" + build-date "2005-09-12" + maintainer "Aidan Kehoe " + distribution xemacs + priority medium + category "standard" + dump nil + description "Interactive development tool for regular expressions." + filename "re-builder-1.05-pkg.tar.gz" + md5sum "da77f41112a0f92416ca74fd26b23aee" + size 20729 + provides (re-builder) + requires () + type regular +)) +)) +;;;@@@ +(package-get-update-base-entry (quote +(latin-euro-standards + (standards-version 1.1 + version "1.07" + author-version "1.07" + date "2005-06-29" + build-date "2005-06-29" + maintainer "Aidan Kehoe " + distribution mule + priority high + category "mule" + dump nil + description "MULE: Support for the Latin{7,8,9,10} character sets & coding systems." + filename "latin-euro-standards-1.07-pkg.tar.gz" + md5sum "1557507199aa08bb8b292e02af543f9d" + size 13887 + provides () + requires (mule-base) + type regular +)) +)) +;;;@@@ +(package-get-update-base-entry (quote +(xwem + (standards-version 1.1 + version "1.21" + author-version "lg@xwem.org--2005/xwem--main--2.1--versionfix-1" + date "2005-04-09" + build-date "2005-04-09" + maintainer "Zajcev Evgeny " + distribution xemacs + priority low + category "standard" + dump nil + description "X Emacs Window Manager." + filename "xwem-1.21-pkg.tar.gz" + md5sum "766dbbfba485e1ed1d7a6d289d73ff21" + size 649651 + provides (ixwem xwem-appcollect xwem-battery xwem-clgen + xwem-clients xwem-clswi xwem-compat xwem-desktop + xwem-diagram xwem-edmacro xwem-edprops xwem-events + xwem-faces xwem-focus xwem-frame xwem-framei + xwem-frametrans xwem-gamma xwem-help xwem-holer + xwem-icons xwem-interactive xwem-keyboard xwem-keydefs + xwem-keymacro xwem-keytt xwem-launcher xwem-load + xwem-loaddefs xwem-macros xwem-main xwem-manage + xwem-minibuffer xwem-misc xwem-modes xwem-mouse + xwem-netwm xwem-osd xwem-pager xwem-ratanot xwem-recover + xwem-register xwem-report xwem-root xwem-rooter + xwem-rooticon xwem-selections xwem-smartmods xwem-sound + xwem-special xwem-strokes xwem-struct xwem-tabbing + xwem-theme xwem-time xwem-transient xwem-tray xwem-version + xwem-vert xwem-weather xwem-win xwem-worklog xwem-xfig) + requires (xwem xemacs-base xlib strokes edit-utils text-modes time slider elib ilisp mail-lib) + type regular +)) +)) +;;;@@@ +(package-get-update-base-entry (quote +(escreen + (standards-version 1.1 + version "1.01" + author-version "1.16" + date "2004-03-15" + build-date "2004-03-15" + maintainer "Jan Rychter " + distribution xemacs + priority low + category "standard" + dump nil + description "Multiple editing sessions withing a single frame (like screen)." + filename "escreen-1.01-pkg.tar.gz" + md5sum "2998cd0d7a90b89a3c3860549c43622a" + size 14639 + provides (escreen) + requires (xemacs-base) + type regular +)) +)) +;;;@@@ +(package-get-update-base-entry (quote +(xlib + (standards-version 1.1 + version "1.14" + author-version "lg@xwem.org--2005/xlib--main--2.1--version-0" + date "2005-04-05" + build-date "2005-04-05" + maintainer "Zajcev Evgeny " + distribution xemacs + priority low + category "standard" + dump nil + description "Emacs interface to X server." + filename "xlib-1.14-pkg.tar.gz" + md5sum "0d3adfa462bebb9009d20b0623d23664" + size 205806 + provides (xlib-composer xlib-const xlib-hello xlib-img xlib-keysymdb xlib-math xlib-testing xlib-tray xlib-version xlib-vidmode xlib-xc xlib-xdpms xlib-xinerama xlib-xlib xlib-xpm xlib-xr xlib-xrecord xlib-xshape xlib-xtest xlib-xwin) + requires (xlib xemacs-base) + type regular +)) +)) +;;;@@@ +(package-get-update-base-entry (quote +(erc + (standards-version 1.0 + version "0.19" + author-version "Version 5.0 Revision: 1.776" + date "2005-10-21" + build-date "2005-10-21" + maintainer "Adrian Aichner " + distribution stable + priority low + category "standard" + dump nil + description "ERC is an Emacs InternetRelayChat client." + filename "erc-0.19-pkg.tar.gz" + md5sum "3ec5279835c74460981e76b169aab269" + size 461162 + provides (erc) + requires (edit-utils fsf-compat gnus pcomplete xemacs-base text-modes ispell viper) + type regular +)) +)) +;;;@@@ +(package-get-update-base-entry (quote +(general-docs + (standards-version 1.1 + version "1.04" author-version "No-Upstream-Ver" - date "2003-10-31" - build-date "2003-10-31" + date "2005-05-07" + build-date "2005-05-07" maintainer "XEmacs Development Team " distribution xemacs priority high category "standard" dump nil description "General XEmacs documentation." - filename "general-docs-1.01-pkg.tar.gz" - md5sum "06c3e4e0aeddd995f2697c91a6b8cc00" - size 1435 + filename "general-docs-1.04-pkg.tar.gz" + md5sum "0d55fe74b8cc9a5a1d34e27e2d096ec1" + size 43374 provides () requires () type regular @@ -28,21 +197,21 @@ (package-get-update-base-entry (quote (riece (standards-version 1.1 - version "1.12" - author-version "0.1.5" - date "2003-10-29" - build-date "2003-10-29" + version "1.21" + author-version "2.0.2" + date "2005-11-21" + build-date "2005-11-21" maintainer "Daiki Ueno " distribution xemacs priority high category "standard" dump nil description "IRC (Internet Relay Chat) client for Emacs." - filename "riece-1.12-pkg.tar.gz" - md5sum "8859cfde4a93a31407e29c35a35e9669" - size 106360 - provides (riece-compat riece-xemacs riece-globals riece-options riece-version riece-coding riece-complete riece-identity riece-channel riece-user riece-misc riece-layout riece-display riece-server riece-naming riece-message riece-filter riece-handle riece-000 riece-200 riece-300 riece-400 riece-500 riece-commands riece riece-ctcp riece-highlight riece-log riece-mini riece-rdcc riece-url riece-unread riece-doctor riece-alias riece-guess riece-history riece-button riece-keyword riece-menu riece-icon) - requires (xemacs-base mail-lib) + filename "riece-1.21-pkg.tar.gz" + md5sum "69dad9e533297eb21313dde7b8ce0026" + size 198929 + provides (riece-compat riece-xemacs riece-globals riece-options riece-debug riece-version riece-coding riece-complete riece-addon-modules riece-addon riece-ruby riece-cache riece-mode riece-identity riece-channel riece-user riece-misc riece-signal riece-layout riece-display riece-server riece-naming riece-message riece-filter riece-handle riece-000 riece-200 riece-300 riece-400 riece-500 riece-commands riece-irc riece riece-alias riece-async riece-biff riece-button riece-ctcp riece-ctlseq riece-doctor riece-eval-ruby riece-eval riece-foolproof riece-google riece-guess riece-hangman riece-highlight riece-history riece-icon riece-ignore riece-kakasi riece-keepalive riece-keyword riece-log riece-lsdb riece-menu riece-mini riece-rdcc riece-shrink-buffer riece-skk-kakutei riece-toolbar riece-unread riece-url riece-xface riece-xfaceb riece-yank) + requires (xemacs-base mail-lib bbdb) type regular )) )) @@ -72,19 +241,19 @@ (package-get-update-base-entry (quote (hyperbole (standards-version 1.0 - version "1.13" + version "1.16" author-version "4.18" - date "2003-10-31" - build-date "2003-10-31" + date "2004-06-13" + build-date "2004-06-13" maintainer "Mats Lidell " distribution stable priority high category "standard" dump nil description "Hyperbole: The Everyday Info Manager" - filename "hyperbole-1.13-pkg.tar.gz" - md5sum "fed416810d33560f433c4ad0bef605bc" - size 634192 + filename "hyperbole-1.16-pkg.tar.gz" + md5sum "64be21a91b7ef00696b19478ccef90f6" + size 636211 provides (hact hactypes hargs hbdata hbmap hbut hgnus hhist hib-doc-id hib-kbd hibtypes hinit hlvar hmail hmh hmoccur hmous-info hmouse-drv hmouse-key hmouse-mod hmouse-tag hpath hrmail hsite hsmail hsys-w3 hsys-wais htz hui-menu hui-mini hui-mouse hui-window hui-xe-but hui hvar hversion hvm hypb hyperbole set wconfig wrolo-logic wrolo-menu wrolo) requires (xemacs-base mail-lib calendar vm text-modes gnus mh-e rmail apel tm sh-script net-utils) type regular @@ -94,20 +263,20 @@ (package-get-update-base-entry (quote (ecb (standards-version 1.1 - version "1.13" - author-version "1.96" - date "2003-10-31" - build-date "2003-10-31" + version "1.22" + author-version "2.31" + date "2004-12-22" + build-date "2004-12-22" maintainer "Klaus Berndl " distribution xemacs priority low category "standard" dump nil description "Emacs source code browser." - filename "ecb-1.13-pkg.tar.gz" - md5sum "dbbc4f68db8f2f294b89f0ee11ae6156" - size 525836 - provides (ecb-buffertab ecb-compilation ecb-create-layout ecb-cycle ecb ecb-eshell ecb-examples ecb-face ecb-help ecb-layout ecb-layout-defs ecb-mode-line ecb-navigate ecb-speedbar ecb-tod ecb-autogen ecb-jde ecb-upgrade ecb-util ecb-winman-support silentcomp tree-buffer) + filename "ecb-1.22-pkg.tar.gz" + md5sum "ebce6137e59c2792b3960bce293f0ec1" + size 887270 + provides (ecb-buffertab ecb-compilation ecb-create-layout ecb-cycle ecb ecb-eshell ecb-examples ecb-face ecb-file-browser ecb-help ecb-layout ecb-layout-defs ecb-method-browser ecb-mode-line ecb-navigate ecb-speedbar ecb-tod ecb-autogen ecb-jde ecb-upgrade ecb-util ecb-winman-support ecb-semantic-wrapper silentcomp tree-buffer ecb-compatibility ecb-common-browser) requires (xemacs-base semantic eieio fsf-compat edit-utils jde mail-lib eshell ediff xemacs-devel speedbar c-support) type regular )) @@ -116,21 +285,21 @@ (package-get-update-base-entry (quote (pgg (standards-version 1.1 - version "1.04" + version "1.06" author-version "0.1" - date "2003-10-31" - build-date "2003-10-31" + date "2005-09-26" + build-date "2005-09-26" maintainer "Simon Josefsson " distribution xemacs priority low category "standard" dump nil description "Emacs interface to various PGP implementations." - filename "pgg-1.04-pkg.tar.gz" - md5sum "8f4d77a0e99edbd3040c8d3988109ee8" - size 31307 + filename "pgg-1.06-pkg.tar.gz" + md5sum "6cb9d38dfe23cdd8ff62291be5a8b03a" + size 33917 provides (pgg pgg-def pgg-parse pgg-gpg pgg-pgp pgg-pgp5) - requires (xemacs-base fsf-compat edebug) + requires (xemacs-base fsf-compat edebug ecrypto) type regular )) )) @@ -138,19 +307,19 @@ (package-get-update-base-entry (quote (perl-modes (standards-version 1.1 - version "1.05" + version "1.08" author-version "No-Upstream-Ver" - date "2003-10-31" - build-date "2003-10-31" + date "2005-04-27" + build-date "2005-04-28" maintainer "XEmacs Development Team " distribution xemacs priority low category "standard" dump nil description "Perl support." - filename "perl-modes-1.05-pkg.tar.gz" - md5sum "cbfc241502bb708e878bcb2d587a78b1" - size 161184 + filename "perl-modes-1.08-pkg.tar.gz" + md5sum "b35612e5ac120e2d875899f2314cfa85" + size 165731 provides (cperl-mode perl-mode) requires (xemacs-base ispell ps-print edit-utils fsf-compat) type regular @@ -160,21 +329,21 @@ (package-get-update-base-entry (quote (python-modes (standards-version 1.1 - version "1.03" + version "1.07" author-version "No-Upstream-Ver" - date "2003-10-31" - build-date "2003-10-31" - maintainer "XEmacs Development Team " + date "2005-12-19" + build-date "2005-12-19" + maintainer "Skip Montanaro " distribution xemacs priority low category "standard" dump nil description "Python support." - filename "python-modes-1.03-pkg.tar.gz" - md5sum "537b318e5901cfc95ba7dfcce32d24bf" - size 82105 + filename "python-modes-1.07-pkg.tar.gz" + md5sum "574cac0c86f8e19c684017989ea25801" + size 92924 provides (pydoc python-mode) - requires (xemacs-base mail-lib) + requires (xemacs-base mail-lib edit-utils fsf-compat) type regular )) )) @@ -204,19 +373,19 @@ (package-get-update-base-entry (quote (fortran-modes (standards-version 1.1 - version "1.03" + version "1.05" author-version "No-Upstream-Ver" - date "2003-10-31" - build-date "2003-10-31" + date "2005-12-20" + build-date "2005-12-20" maintainer "XEmacs Development Team " distribution xemacs priority low category "standard" dump nil description "Fortran support." - filename "fortran-modes-1.03-pkg.tar.gz" - md5sum "413d2f5ea1497c29b436fee52073563b" - size 66719 + filename "fortran-modes-1.05-pkg.tar.gz" + md5sum "2c2545602482660ad0d811b0574a3eed" + size 70602 provides (f90 fortran) requires (xemacs-base) type regular @@ -270,21 +439,21 @@ (package-get-update-base-entry (quote (ecrypto (standards-version 1.1 - version "0.14" + version "0.20" author-version "2.0" - date "2003-10-31" - build-date "2003-10-31" + date "2005-09-26" + build-date "2005-09-26" maintainer "Simon Josefsson " distribution xemacs priority low category "standard" dump nil description "Crypto functionality in Emacs Lisp." - filename "ecrypto-0.14-pkg.tar.gz" - md5sum "59207e5f5a5300ccf0d21f27b018de91" - size 68741 + filename "ecrypto-0.20-pkg.tar.gz" + md5sum "eb94f451a4d279cd92f8f2bcb9b9b79b" + size 76257 provides (ascii-armor blowfish des hex-util md4 md5-dl md5-el md5 paranoid rander rc16 rijndael sha1-dl sha1-el sha1) - requires () + requires (xemacs-base) type regular )) )) @@ -314,19 +483,19 @@ (package-get-update-base-entry (quote (sasl (standards-version 1.1 - version "1.14" + version "1.16" author-version "1.14.4" - date "2003-10-31" - build-date "2003-10-31" + date "2005-09-26" + build-date "2005-09-26" maintainer "Simon Josefsson " distribution xemacs priority low category "standard" dump nil description "Simple Authentication and Security Layer (SASL) library." - filename "sasl-1.14-pkg.tar.gz" - md5sum "a00a2f0e7e6f1614ae95cdbef50e333e" - size 27045 + filename "sasl-1.16-pkg.tar.gz" + md5sum "2799ab3b97e3d3cd2fd5ca0385b04931" + size 27864 provides (hmac-def hmac-md5 hmac-sha1 ntlm sasl sasl-cram sasl-digest sasl-ntlm sasl-plain sasl-login sasl-anonymous) requires (ecrypto) type regular @@ -336,19 +505,19 @@ (package-get-update-base-entry (quote (sml-mode (standards-version 1.1 - version "0.10" + version "0.12" author-version "3.9.5" - date "2003-10-31" - build-date "2003-10-31" + date "2005-07-27" + build-date "2005-07-27" maintainer "XEmacs Development Team " distribution xemacs priority low category "standard" dump nil description "SML editing support." - filename "sml-mode-0.10-pkg.tar.gz" - md5sum "87914cf428610799a98815b17393f6e0" - size 81763 + filename "sml-mode-0.12-pkg.tar.gz" + md5sum "017614793fe793e401911c0824356a37" + size 82366 provides (sml-compat sml-defs sml-mode sml-move sml-proc sml-util) requires (xemacs-base edebug fsf-compat) type regular @@ -356,43 +525,21 @@ )) ;;;@@@ (package-get-update-base-entry (quote -(ess - (standards-version 1.1 - version "1.06" - author-version "5.1.21" - date "2003-11-10" - build-date "2003-11-10" - maintainer "A.J. Rossini " - distribution xemacs - priority medium - category "standard" - dump nil - description "ESS: Emacs Speaks Statistics." - filename "ess-1.06-pkg.tar.gz" - md5sum "46e105b2fd715790f6358d9f637cdf32" - size 445788 - provides (ess-batch ess-comp ess-cust ess-dump ess-emcs ess-font-lock ess-help ess-inf ess-iw32 ess-latex-mode ess-menu ess-mode ess-mous ess-noweb ess-site ess-sysdp ess-utils ess-vars ess essa-r essa-sas essd-arc essd-els essd-r essd-omg essd-r essd-s3 essd-s4 essd-sas essd-sp3 essd-sp4 essd-sp5 essd-sp6 essd-sta essd-vst essd-xls essddr essdsp6w essl-bug essl-lsp essl-omg essl-py essl-s essl-sas essl-sta make-regexp mouseme msdos noweb-font-lock-mode noweb-mode) - requires (xemacs-base mail-lib fsf-compat edit-utils speedbar sh-script eterm) - type regular -)) -)) -;;;@@@ -(package-get-update-base-entry (quote (haskell-mode (standards-version 1.1 - version "1.06" - author-version "1.44" - date "2003-10-31" - build-date "2003-10-31" - maintainer "XEmacs Development Team " + version "1.07" + author-version "1.45" + date "2004-06-16" + build-date "2004-06-16" + maintainer "Jerry James " distribution xemacs priority low category "standard" dump nil description "Haskell editing support." - filename "haskell-mode-1.06-pkg.tar.gz" - md5sum "75c3dcb6fbe0a8824c865d8b989866cc" - size 94315 + filename "haskell-mode-1.07-pkg.tar.gz" + md5sum "20d1ff41a4b753a276affd60850b08e7" + size 97642 provides (haskell-decl-scan haskell-doc haskell-font-lock haskell-indent haskell-mode haskell-simple-indent) requires (dired mail-lib xemacs-base edit-utils) type regular @@ -422,45 +569,23 @@ )) ;;;@@@ (package-get-update-base-entry (quote -(liece - (standards-version 1.1 - version "1.12" - author-version "1.4.9" - date "2003-04-22" - build-date "2003-04-22" - maintainer "Daiki Ueno " - distribution xemacs - priority high - category "standard" - dump nil - description "IRC (Internet Relay Chat) client for Emacs." - filename "liece-1.12-pkg.tar.gz" - md5sum "c7f2aab45f8ada9398d4b0807e80433a" - size 199275 - provides (liece-xemacs gettext liece-clfns liece-handler liece-compat liece-version liece-vars liece-globals liece-inlines liece-filter liece-coding liece-dcc liece-menu liece-000 liece-200 liece-300 liece-400 liece-500 liece-nick liece-channel liece-commands liece-ctcp liece-q-el liece-message liece-handle liece-hilit liece-intl liece-mail liece-minibuf liece-misc liece-tcp liece-url liece-x-face liece-window liece) - requires (apel mail-lib fsf-compat xemacs-base) - type regular -)) -)) -;;;@@@ -(package-get-update-base-entry (quote (latin-unity (standards-version 1.1 - version "1.09" - author-version "1.09" - date "2003-11-09" - build-date "2003-11-09" + version "1.16" + author-version "1.16" + date "2005-12-29" + build-date "2005-12-29" maintainer "Stephen J. Turnbull " distribution mule priority high category "mule" dump nil description "MULE: find single ISO 8859 character set to encode a buffer." - filename "latin-unity-1.09-pkg.tar.gz" - md5sum "83b7fd603ad7cd5d9c459a0035501cac" - size 106267 + filename "latin-unity-1.16-pkg.tar.gz" + md5sum "2591f33d4c1057c238efe124ff534c81" + size 104739 provides (latin-unity latin-unity-tables latin-unity-utils) - requires (mule-base mule-ucs leim fsf-compat dired) + requires (mule-base latin-euro-standards mule-ucs leim fsf-compat dired) type regular )) )) @@ -468,19 +593,19 @@ (package-get-update-base-entry (quote (mmm-mode (standards-version 1.1 - version "1.01" + version "1.02" author-version "0.4.7" - date "2003-10-29" - build-date "2003-10-29" + date "2004-03-02" + build-date "2004-03-02" maintainer "XEmacs Development Team " distribution xemacs priority medium category "standard" dump nil description "Multiple major modes in a single buffer" - filename "mmm-mode-1.01-pkg.tar.gz" - md5sum "28cf0136d0d8e59e74a464074a98ef4b" - size 175927 + filename "mmm-mode-1.02-pkg.tar.gz" + md5sum "f68f90fb1b870f7a8e89c83e9b6c3973" + size 176072 provides (mmm-auto mmm-class mmm-cmds mmm-compat mmm-mason mmm-mode mmm-region mmm-rpm mmm-sample mmm-univ mmm-utils mmm-vars) requires (xemacs-base fsf-compat ) type regular @@ -512,19 +637,19 @@ (package-get-update-base-entry (quote (xemacs-base (standards-version 1.1 - version "1.82" + version "2.01" author-version "No-Upstream-Ver" - date "2003-10-29" - build-date "2003-10-29" + date "2005-12-31" + build-date "2005-12-31" maintainer "XEmacs Development Team " distribution xemacs priority high category "standard" dump nil description "Fundamental XEmacs support, you almost certainly need this." - filename "xemacs-base-1.82-pkg.tar.gz" - md5sum "7ba84839d26de61e4cb62741531d59ba" - size 472771 + filename "xemacs-base-2.01-pkg.tar.gz" + md5sum "a378f0ed585ebb9d6d8ace534f7e5987" + size 513382 provides (add-log advice-preload advice annotations assoc case-table chistory comint-xemacs comint compile debug ebuff-menu echistory edmacro ehelp electric enriched env facemenu ffap helper imenu iso-syntax macros novice outline passwd pp regexp-opt regi ring shell skeleton sort thing time-stamp timezone tq xbm-button xpm-button) requires () type regular @@ -534,22 +659,22 @@ (package-get-update-base-entry (quote (tramp (standards-version 1.1 - version "1.16" - author-version "2.0.35" - date "2003-07-21" - build-date "2003-07-21" + version "1.28" + author-version "2.0.51" + date "2005-10-12" + build-date "2005-10-12" maintainer "Kai Großjohann " distribution xemacs priority low category "standard" dump nil description "Remote shell-based file editing." - filename "tramp-1.16-pkg.tar.gz" - md5sum "ec5a21c4462d48ebe8dc01ea0e32373c" - size 251091 + filename "tramp-1.28-pkg.tar.gz" + md5sum "5ac2f914804150d00cba64c717182c59" + size 291435 provides (tramp tramp-efs tramp-ftp tramp-smb tramp-util tramp-uu tramp-vc trampcache) - requires (tramp xemacs-base vc fsf-compat efs dired mail-lib gnus ediff) + requires (tramp xemacs-base vc efs dired mail-lib gnus ediff sh-script) type regular )) )) @@ -557,20 +682,20 @@ (package-get-update-base-entry (quote (text-modes (standards-version 1.1 - version "1.71" + version "1.90" author-version "No-Upstream-Ver" - date "2003-11-13" - build-date "2003-11-13" + date "2005-11-02" + build-date "2005-11-02" maintainer "XEmacs Development Team " distribution xemacs priority high category "standard" dump nil description "Miscellaneous support for editing text files." - filename "text-modes-1.71-pkg.tar.gz" - md5sum "39be167962dc1a547a13f8bb1788327f" - size 377506 - provides (ansi-color autoinsert crontab-edit desktop-entry-mode filladapt flyspell folding fold-isearch hexl htmlize image-mode iso-acc iso-ascii iso-cvt iso-insert iso-swed rtf-support swedish tabify whitespace-mode winmgr-mode xpm-mode xrdb-mode apache-mode po-mode po-compat css-mode) + filename "text-modes-1.90-pkg.tar.gz" + md5sum "f2d5111f6e561b595aead30333b704cf" + size 442526 + provides (ansi-color autoinsert crontab-edit desktop-entry-mode filladapt flyspell folding fold-isearch hexl htmlize image-mode iso-acc iso-ascii iso-cvt iso-insert iso-swed rtf-support swedish tabify whitespace-mode whitespace-visual-mode winmgr-mode xpm-mode xrdb-mode apache-mode po-mode po-compat css-mode) requires (ispell fsf-compat xemacs-base) type regular )) @@ -579,20 +704,20 @@ (package-get-update-base-entry (quote (pcl-cvs (standards-version 1.1 - version "1.65" + version "1.66" author-version "R-2_9_9" - date "2003-10-31" - build-date "2003-10-31" + date "2004-12-22" + build-date "2004-12-22" maintainer "XEmacs Development Team " distribution xemacs priority low category "standard" dump nil description "CVS frontend." - filename "pcl-cvs-1.65-pkg.tar.gz" - md5sum "53b8cbd4d0b7709cfaf9d51e11888324" - size 161016 - provides (cvs-compat cvs-edit cvs-log cvs-status easy-mmode pcl-cvs-defs pcl-cvs-info pcl-cvs-parse pcl-cvs-util pcl-cvs) + filename "pcl-cvs-1.66-pkg.tar.gz" + md5sum "04101b03e5d8e929471875b30e1a2c31" + size 161505 + provides (cvs-compat cvs-edit cvs-log cvs-status pcl-cvs-defs pcl-cvs-info pcl-cvs-parse pcl-cvs-util pcl-cvs) requires (xemacs-base elib vc dired edebug ediff edit-utils mail-lib prog-modes) type regular )) @@ -601,19 +726,19 @@ (package-get-update-base-entry (quote (mail-lib (standards-version 1.1 - version "1.63" + version "1.75" author-version "No-Upstream-Ver" - date "2003-10-31" - build-date "2003-10-31" + date "2005-10-28" + build-date "2005-10-28" maintainer "Simon Josefsson " distribution xemacs priority medium category "standard" dump nil description "Fundamental lisp files for providing email support." - filename "mail-lib-1.63-pkg.tar.gz" - md5sum "99b3f341e8c29ad2dc3fec5196e32549" - size 198134 + filename "mail-lib-1.75-pkg.tar.gz" + md5sum "a8417567fe05e5baf884e1993bf13a44" + size 211214 provides (base64 browse-url-xemacs browse-url highlight-headers mail-abbrevs mail-extr mail-utils mailheader netrc pop3 reporter rfc2104 rfc822 rmail rmail-mini rmailout sendmail smtpmail starttls tls) requires (eterm xemacs-base fsf-compat sh-script ecrypto) type regular @@ -623,19 +748,19 @@ (package-get-update-base-entry (quote (jde (standards-version 1.1 - version "1.46" + version "1.48" author-version "2.3.2" - date "2003-10-08" - build-date "2003-10-08" + date "2005-06-01" + build-date "2005-06-01" maintainer "Andy Piper " distribution xemacs priority medium category "standard" dump nil description "Integrated Development Environment for Java." - filename "jde-1.46-pkg.tar.gz" - md5sum "60f5d299a53be811f6ef6006f2566c20" - size 2403395 + filename "jde-1.48-pkg.tar.gz" + md5sum "26a98e47f6358b465f423dc9d597c6f6" + size 2404962 provides (beanshell efc jde-ant jde-bug jde-checkstyle jde-compat jde-compile jde-complete jde-db jde-dbo jde-dbs jde-ejb jde-gen jde-help jde-imenu jde-import jde-java-font-lock jde-java-grammar jde-javadoc-gen jde-javadoc jde-jdb jde-make jde-open-source jde-package jde-parse-class jde-parse jde-run jde-setnu jde-stat jde-util jde-which-method jde-widgets jde-wiz jde-xref jde tree-widget) requires (jde cc-mode semantic debug speedbar edit-utils eterm mail-lib xemacs-base xemacs-devel eieio elib sh-script fsf-compat) type regular @@ -645,19 +770,19 @@ (package-get-update-base-entry (quote (fsf-compat (standards-version 1.1 - version "1.13" + version "1.15" author-version "No-Upstream-Ver" - date "2003-10-31" - build-date "2003-10-31" + date "2004-10-22" + build-date "2004-10-22" maintainer "XEmacs Development Team " distribution xemacs priority high category "standard" dump nil description "FSF Emacs compatibility files." - filename "fsf-compat-1.13-pkg.tar.gz" - md5sum "270a9deea6166bb38ac00f6191c7e8c0" - size 21687 + filename "fsf-compat-1.15-pkg.tar.gz" + md5sum "a68d000cf16b054b20a56e917d57e712" + size 18912 provides (overlay thingatpt timer x-popup-menu goto-addr) requires (xemacs-base) type single @@ -667,19 +792,19 @@ (package-get-update-base-entry (quote (edit-utils (standards-version 1.1 - version "2.10" + version "2.32" author-version "No-Upstream-Ver" - date "2003-10-31" - build-date "2003-10-31" + date "2005-12-05" + build-date "2005-12-05" maintainer "XEmacs Development Team " distribution xemacs priority high category "standard" dump nil description "Miscellaneous editor extensions, you probably need this." - filename "edit-utils-2.10-pkg.tar.gz" - md5sum "8d3c77a3ae8fb443a608a148e32e0d48" - size 925330 + filename "edit-utils-2.32-pkg.tar.gz" + md5sum "c858e39c25478b3797a5859c991d7bc9" + size 944596 provides (abbrevlist after-save-commands atomic-extents avoid backup-dir balloon-help big-menubar blink-cursor blink-paren bookmark compare-w completion dabbrev desktop detached-minibuf edit-toolbar fast-lock file-part floating-toolbar flow-ctrl foldout func-menu hippie-exp icomplete id-select info-look iswitchb lazy-lock lazy-shot live-icon makesum man mic-paren paren mode-motion+ outl-mouse outln-18 page-ext blink-paren paren permanent-buffers popper power-macros recent-files redo reportmail resume rsz-minibuf saveconf savehist saveplace scroll-in-place setnu shell-font tempo toolbar-utils tree-menu uniquify vertical-mode where-was-i-db winring autorevert align allout outline narrow-stack highline) requires (xemacs-base xemacs-devel fsf-compat dired mail-lib) type single @@ -711,19 +836,19 @@ (package-get-update-base-entry (quote (ps-print (standards-version 1.1 - version "1.09" + version "1.11" author-version "6.5.6" - date "2003-10-31" - build-date "2003-10-31" + date "2004-08-10" + build-date "2004-08-10" maintainer "XEmacs Development Team " distribution xemacs priority medium category "standard" dump nil description "Printing functions and utilities" - filename "ps-print-1.09-pkg.tar.gz" - md5sum "9055fe7244e253e2a12cc7e4d69df041" - size 155737 + filename "ps-print-1.11-pkg.tar.gz" + md5sum "a9460da8906bbbcbec37f28625b2bbad" + size 156222 provides (lpr ps-bdf ps-mule ps-print) requires (text-modes) type regular @@ -733,21 +858,21 @@ (package-get-update-base-entry (quote (sieve (standards-version 1.1 - version "1.14" + version "1.18" author-version "No-Upstream-Ver" - date "2003-10-31" - build-date "2003-10-31" + date "2005-09-26" + build-date "2005-09-26" maintainer "Simon Josefsson " distribution xemacs priority low category "standard" dump nil description "Manage Sieve email filtering scripts." - filename "sieve-1.14-pkg.tar.gz" - md5sum "6a9234ad3e59c485869db92a3637d91f" - size 25677 + filename "sieve-1.18-pkg.tar.gz" + md5sum "254bfbb81e4204ab8e57066baee8e78f" + size 27387 provides (sieve sieve-mode sieve-manage) - requires (xemacs-base mail-lib cc-mode sasl) + requires (xemacs-base mail-lib cc-mode sasl ecrypto sh-script) type regular )) )) @@ -755,21 +880,21 @@ (package-get-update-base-entry (quote (mule-ucs (standards-version 1.1 - version "1.05" + version "1.14" author-version "0.84" - date "2003-10-31" - build-date "2003-10-31" + date "2005-06-21" + build-date "2005-06-21" maintainer "Stephen J. Turnbull " distribution mule priority high category "mule" dump nil description "MULE: Extended coding systems (including Unicode) for XEmacs." - filename "mule-ucs-1.05-pkg.tar.gz" - md5sum "772c06a697d0b3b4d7b78e8df76c019c" - size 1314530 + filename "mule-ucs-1.14-pkg.tar.gz" + md5sum "b1e0eb84dc1675400b867a57d38ffb36" + size 1300714 provides (mccl-font mucs-ccl mucs-error mucs-type mucs mule-uni tae tbl-mg trans-util txt-tbl un-data un-define un-supple un-tools un-trbase unicode unidata utf u-cns-1 u-cns-2 u-cns-3 u-cns-4 u-cns-5 u-cns-6 u-cns-7 uascii ubig5 uetiopic ugb2312 uipa uiscii uiso8859-1 uiso8859-14 uiso8859-15 uiso8859-2 uiso8859-3 uiso8859-4 uiso8859-5 uiso8859-6 uiso8859-7 uiso8859-8 uiso8859-9 ujisx0201 ujisx0208 ujisx0212 uksc5601 usisheng usupple utibetan utis620 uviscii) - requires (mule-base) + requires (mule-base latin-euro-standards) type regular )) )) @@ -777,21 +902,21 @@ (package-get-update-base-entry (quote (clearcase (standards-version 1.0 - version "1.08" - author-version "No-Upstream-Ver" - date "2003-10-31" - build-date "2003-10-31" - maintainer "Michael Diers " + version "1.10" + author-version "/main/laptop/165" + date "2005-06-04" + build-date "2005-06-04" + maintainer "Adrian Aichner " distribution xemacs priority low category "standard" dump nil description "New Clearcase Version Control for XEmacs (UNIX, Windows)." - filename "clearcase-1.08-pkg.tar.gz" - md5sum "6fedc7464137eae08c25517276f8a7ab" - size 94543 + filename "clearcase-1.10-pkg.tar.gz" + md5sum "956e445057c6c1afd48d898b9736bd22" + size 105865 provides (clearcase) - requires (dired fsf-compat mail-lib xemacs-base) + requires (dired mail-lib xemacs-base sh-script) type regular )) )) @@ -799,19 +924,19 @@ (package-get-update-base-entry (quote (dictionary (standards-version 1.1 - version "1.12" + version "1.16" author-version "1.8" - date "2003-06-22" - build-date "2003-06-22" + date "2005-05-10" + build-date "2005-05-10" maintainer "Torsten Hilbrich " distribution xemacs priority low category "standard" dump nil description "Interface to RFC2229 dictionary servers." - filename "dictionary-1.12-pkg.tar.gz" - md5sum "717517bbad4e241f18941fd6c289b868" - size 39658 + filename "dictionary-1.16-pkg.tar.gz" + md5sum "83011986c60b22aecb5c1246f66c7744" + size 40085 provides (dictionary connection link) requires (xemacs-base) type regular @@ -843,19 +968,19 @@ (package-get-update-base-entry (quote (xslt-process (standards-version 1.0 - version "1.11" + version "1.12" author-version "1.2.1" - date "2002-10-08" - build-date "2002-10-08" + date "2005-07-27" + build-date "2005-07-27" maintainer "Ovidiu Predescu " distribution xemacs priority medium category "standard" dump nil description "XSLT processing support." - filename "xslt-process-1.11-pkg.tar.gz" - md5sum "30273cbe2e90ae703ea410879412e68b" - size 199873 + filename "xslt-process-1.12-pkg.tar.gz" + md5sum "dde00a263877a3bb3a82c6fb96299aab" + size 59594 provides (xslt-process) requires (jde cc-mode semantic debug speedbar edit-utils eterm mail-lib xemacs-base elib eieio sh-script fsf-compat xemacs-devel) type regular @@ -931,19 +1056,19 @@ (package-get-update-base-entry (quote (lookup (standards-version 1.1 - version "1.14" + version "1.15" author-version "1.0" - date "2003-10-31" - build-date "2003-10-31" + date "2005-05-10" + build-date "2005-05-10" maintainer "XEmacs Development Team " distribution mule priority high category "mule" dump nil description "MULE: Dictionary support" - filename "lookup-1.14-pkg.tar.gz" - md5sum "f48776563d7fbd0852ad73ac9c513260" - size 225996 + filename "lookup-1.15-pkg.tar.gz" + md5sum "975f4d8435cae628e7c6338115a3a542" + size 225952 provides (evi-mule evi lookup-content lookup-defs lookup-entry lookup-select lookup-package lookup-select lookup-types lookup-utils lookup-vars lookup-vse lookup ndcookie ndeb ndic ndict ndkks ndmisc ndnmz ndspell ndsrd ndtp sdicf stem) requires (mule-base cookie lookup) type regular @@ -975,19 +1100,19 @@ (package-get-update-base-entry (quote (locale (standards-version 1.1 - version "1.21" + version "1.22" author-version "No-Upstream-Ver" - date "2003-10-31" - build-date "2003-10-31" + date "2004-12-07" + build-date "2004-12-07" maintainer "XEmacs Development Team " distribution mule priority high category "mule" dump nil description "MULE: Localized menubars and localized splash screens." - filename "locale-1.21-pkg.tar.gz" - md5sum "2256243bb8cdd282af7b40bc2cf30018" - size 36961 + filename "locale-1.22-pkg.tar.gz" + md5sum "2a3accb220d0c67b3e76762fb2872ab9" + size 37968 provides () requires (mule-base) type regular @@ -997,19 +1122,19 @@ (package-get-update-base-entry (quote (mule-base (standards-version 1.1 - version "1.44" + version "1.47" author-version "No-Upstream-Ver" - date "2003-10-31" - build-date "2003-10-31" + date "2005-05-10" + build-date "2005-05-10" maintainer "XEmacs Development Team " distribution mule priority high category "mule" dump nil - description "MULE: Basic Mule support, required for building with Mule." - filename "mule-base-1.44-pkg.tar.gz" - md5sum "9eaa93208008617bd8f0d34448dcfaa3" - size 444749 + description "MULE: Basic Mule support." + filename "mule-base-1.47-pkg.tar.gz" + md5sum "f6f85c610f6bd604edcb252b20f32108" + size 444408 provides (canna-leim canna char-table china-util cyril-util isearch-ext japan-util ccl can-n-egg mule-help) requires (fsf-compat xemacs-base apel) type regular @@ -1085,19 +1210,19 @@ (package-get-update-base-entry (quote (sgml (standards-version 1.1 - version "1.10" + version "1.11" author-version "No-Upstream-Ver" - date "2003-10-31" - build-date "2003-10-31" + date "2004-01-27" + build-date "2004-01-27" maintainer "XEmacs Development Team " distribution xemacs priority low category "standard" dump nil description "SGML/Linuxdoc-SGML editing." - filename "sgml-1.10-pkg.tar.gz" - md5sum "ab80262877e3547dfb97e80a0a778e09" - size 27462 + filename "sgml-1.11-pkg.tar.gz" + md5sum "8d1cec5b4b005210507b6fe57e2db9a8" + size 27506 provides (sgml linuxdoc-sgml) requires (xemacs-base) type regular @@ -1107,19 +1232,19 @@ (package-get-update-base-entry (quote (psgml (standards-version 1.1 - version "1.41" + version "1.44" author-version "1.3.1" - date "2003-08-29" - build-date "2003-08-29" + date "2005-04-05" + build-date "2005-04-05" maintainer "XEmacs Development Team " distribution xemacs priority medium category "standard" dump nil description "Validated HTML/SGML editing." - filename "psgml-1.41-pkg.tar.gz" - md5sum "33baca4b85d3d9c48df682b748c9a273" - size 301000 + filename "psgml-1.44-pkg.tar.gz" + md5sum "9edbc1b72754f45d23cf73b287b6a2aa" + size 302065 provides (iso-sgml psgml-api psgml-charent psgml-debug psgml-dtd psgml-edit psgml-fs psgml-html psgml-info psgml-parse psgml-sysdep psgml-xemacs psgml sgml-mode) requires (xemacs-base edit-utils edebug xemacs-devel mail-lib fsf-compat eterm sh-script ps-print) type regular @@ -1129,19 +1254,19 @@ (package-get-update-base-entry (quote (pc (standards-version 1.1 - version "1.26" + version "1.28" author-version "No-Upstream-Ver" - date "2003-10-31" - build-date "2003-10-31" + date "2005-04-26" + build-date "2005-04-26" maintainer "XEmacs Development Team " distribution xemacs priority low category "standard" dump nil description "PC style interface emulation." - filename "pc-1.26-pkg.tar.gz" - md5sum "47189d077b363012c4b17f527eef2ec7" - size 17611 + filename "pc-1.28-pkg.tar.gz" + md5sum "b3722c793e2f9b977fc0967ed0805efa" + size 17720 provides (delbs fusion pc-select pending-del s-region) requires (xemacs-base) type regular @@ -1151,19 +1276,19 @@ (package-get-update-base-entry (quote (ispell (standards-version 1.1 - version "1.26" - author-version "3.3" - date "2003-11-02" - build-date "2003-11-02" + version "1.32" + author-version "3.6" + date "2005-10-16" + build-date "2005-10-16" maintainer "XEmacs Development Team " distribution xemacs priority low category "standard" dump nil description "Spell-checking with GNU ispell." - filename "ispell-1.26-pkg.tar.gz" - md5sum "85a9da0fe8ed41199388b5f41a0f7769" - size 72869 + filename "ispell-1.32-pkg.tar.gz" + md5sum "0eceb13fd90b388f744f04bbf83fe4a1" + size 83587 provides (ispell) requires () type regular @@ -1239,19 +1364,19 @@ (package-get-update-base-entry (quote (calendar (standards-version 1.1 - version "1.22" + version "1.23" author-version "No-Upstream-Ver" - date "2003-10-31" - build-date "2003-10-31" + date "2004-01-27" + build-date "2004-01-27" maintainer "XEmacs Development Team " distribution xemacs priority low category "standard" dump nil description "Calendar and diary support." - filename "calendar-1.22-pkg.tar.gz" - md5sum "c9f0bdbcb3cbbb9eff338e4edd9d7f95" - size 253996 + filename "calendar-1.23-pkg.tar.gz" + md5sum "de5fd826168913232c48aa88ec0f1d5c" + size 254025 provides (appt cal-china cal-coptic cal-dst cal-french cal-hebrew cal-islam cal-iso cal-japanese cal-julian cal-mayan cal-move cal-persia cal-tex cal-x cal-xemacs calendar diary-lib holidays lunar solar) requires (xemacs-base) type regular @@ -1261,19 +1386,19 @@ (package-get-update-base-entry (quote (calc (standards-version 1.1 - version "1.24" + version "1.26" author-version "2.02fX3" - date "2003-10-31" - build-date "2003-10-31" + date "2004-09-07" + build-date "2004-09-07" maintainer "XEmacs Development Team " distribution xemacs priority low category "standard" dump nil description "Emacs calculator" - filename "calc-1.24-pkg.tar.gz" - md5sum "61fa56abe04492e448a8549b5978ca3a" - size 1600141 + filename "calc-1.26-pkg.tar.gz" + md5sum "2ebbdf5c8cba89d50ab6300287697a6b" + size 1600637 provides (calc-ext calc-macs calc) requires (xemacs-base) type regular @@ -1283,19 +1408,19 @@ (package-get-update-base-entry (quote (speedbar (standards-version 1.1 - version "1.27" + version "1.28" author-version "0.14beta4" - date "2003-10-31" - build-date "2003-10-31" + date "2005-07-19" + build-date "2005-07-19" maintainer "Eric M. Ludlam " distribution xemacs priority low category "standard" dump nil description "Provides a separate frame with convenient references." - filename "speedbar-1.27-pkg.tar.gz" - md5sum "4df8d109364493dca814ef7429d560d2" - size 163245 + filename "speedbar-1.28-pkg.tar.gz" + md5sum "1b82aee8431f3c8083689f7a6c3a6a33" + size 163269 provides (bigclock dframe rpm sb-ant sb-gud sb-html sb-image sb-info sb-rmail sb-texinfo sb-w3 speedbar) requires (xemacs-base edebug) type regular @@ -1305,19 +1430,19 @@ (package-get-update-base-entry (quote (pcomplete (standards-version 1.1 - version "1.03" + version "1.04" author-version "1.1.6" - date "2003-10-31" - build-date "2003-10-31" + date "2005-01-23" + build-date "2005-01-23" maintainer "John Wiegley " distribution xemacs priority medium category "standard" dump nil description "Provides programmatic completion." - filename "pcomplete-1.03-pkg.tar.gz" - md5sum "43bad91be873dd6ae2f9483e90c42226" - size 37443 + filename "pcomplete-1.04-pkg.tar.gz" + md5sum "f8631085f1355707234110c9ab043a53" + size 37573 provides (pcomplete) requires (sh-script xemacs-base) type regular @@ -1327,19 +1452,19 @@ (package-get-update-base-entry (quote (eshell (standards-version 1.1 - version "1.06" + version "1.10" author-version "2.4.1" - date "2003-10-31" - build-date "2003-10-31" + date "2005-06-27" + build-date "2005-06-27" maintainer "John Wiegley " distribution xemacs priority medium category "standard" dump nil description "Command shell implemented entirely in Emacs Lisp" - filename "eshell-1.06-pkg.tar.gz" - md5sum "737f4d5caed7ffe8cb987f0e2459d6e8" - size 232041 + filename "eshell-1.10-pkg.tar.gz" + md5sum "859fc15237a3d5177551614fecd88671" + size 232616 provides (em-alias em-banner em-basic em-cmpl em-dirs em-glob em-hist em-ls em-pred em-prompt em-rebind em-script em-smart em-term em-unix em-xtra esh-arg esh-cmd esh-ext esh-io esh-maint esh-mode esh-module esh-opt esh-proc esh-test esh-toggle esh-util esh-var eshell) requires (xemacs-base eterm) type regular @@ -1371,19 +1496,19 @@ (package-get-update-base-entry (quote (os-utils (standards-version 1.1 - version "1.34" + version "1.36" author-version "No-Upstream-Ver" - date "2003-10-31" - build-date "2003-10-31" + date "2005-01-31" + build-date "2005-01-31" maintainer "XEmacs Development Team " distribution xemacs priority medium category "standard" dump nil description "Miscellaneous O/S utilities." - filename "os-utils-1.34-pkg.tar.gz" - md5sum "98fa67e0d1b89febd16bfc952d552171" - size 225849 + filename "os-utils-1.36-pkg.tar.gz" + md5sum "56d04bd914e392d03719206469964f20" + size 225865 provides (archive-mode background crypt++ crypt ftelnet inf-lisp jka-compr mchat rlogin ssh tar-mode telnet terminal uncompress) requires (xemacs-base) type single @@ -1415,19 +1540,19 @@ (package-get-update-base-entry (quote (igrep (standards-version 1.1 - version "1.12" - author-version "2.95" - date "2003-10-31" - build-date "2003-10-31" + version "1.14" + author-version "2.111" + date "2005-12-05" + build-date "2005-12-05" maintainer "XEmacs Development Team " distribution xemacs priority low category "standard" dump nil description "Enhanced front-end for Grep." - filename "igrep-1.12-pkg.tar.gz" - md5sum "a46e749b903ad526dad1a898496e9812" - size 17316 + filename "igrep-1.14-pkg.tar.gz" + md5sum "c67cfd9d4fbb5356784898a54cf957d1" + size 20838 provides (igrep) requires (dired xemacs-base efs) type regular @@ -1437,19 +1562,19 @@ (package-get-update-base-entry (quote (eterm (standards-version 1.1 - version "1.15" + version "1.17" author-version "No-Upstream-Ver" - date "2003-10-31" - build-date "2003-10-31" + date "2005-06-27" + build-date "2005-06-27" maintainer "XEmacs Development Team " distribution xemacs priority medium category "standard" dump nil description "Terminal emulation." - filename "eterm-1.15-pkg.tar.gz" - md5sum "4821611600abfb6f7e6d2d91b361e5dc" - size 109135 + filename "eterm-1.17-pkg.tar.gz" + md5sum "3f0508fad96213912261afdc934e5ce8" + size 109229 provides (eterm) requires (xemacs-base) type regular @@ -1459,19 +1584,19 @@ (package-get-update-base-entry (quote (viper (standards-version 1.1 - version "1.37" + version "1.47" author-version "3.09" - date "2003-10-31" - build-date "2003-10-31" + date "2005-11-25" + build-date "2005-11-25" maintainer "Michael Kifer " distribution xemacs priority low category "standard" dump nil description "VI emulation support." - filename "viper-1.37-pkg.tar.gz" - md5sum "5bd6157ea98d1cc9399e91eb3b684c8c" - size 327719 + filename "viper-1.47-pkg.tar.gz" + md5sum "66e3556c2421cf81083406bc92ad9f88" + size 335017 provides (viper-cmd viper-ex viper-init viper-keym viper-macs viper-mous viper-util viper) requires (xemacs-base) type regular @@ -1525,21 +1650,21 @@ (package-get-update-base-entry (quote (texinfo (standards-version 1.1 - version "1.25" + version "1.30" author-version "No-Upstream-Ver" - date "2003-10-31" - build-date "2003-10-31" + date "2005-09-26" + build-date "2005-09-26" maintainer "XEmacs Development Team " distribution xemacs priority high category "standard" dump nil description "XEmacs TeXinfo support." - filename "texinfo-1.25-pkg.tar.gz" - md5sum "a2755f74e1f4c76ba36d844abc718d3a" - size 133884 + filename "texinfo-1.30-pkg.tar.gz" + md5sum "afa4dfa82a93fc7d4b85096621b8acdf" + size 145763 provides (makeinfo tex-mode texinfmt texinfo texnfo-tex texnfo-upd) - requires (xemacs-base) + requires (text-modes xemacs-base) type regular )) )) @@ -1547,21 +1672,21 @@ (package-get-update-base-entry (quote (reftex (standards-version 1.1 - version "1.33" + version "1.34" author-version "4.21" - date "2003-10-31" - build-date "2003-10-31" + date "2004-03-15" + build-date "2004-03-15" maintainer "Carsten Dominik " distribution xemacs priority medium category "standard" dump nil description "Emacs support for LaTeX cross-references, citations.." - filename "reftex-1.33-pkg.tar.gz" - md5sum "4d9a603199ad55c5d3f3cd31413a56de" - size 352053 + filename "reftex-1.34-pkg.tar.gz" + md5sum "161d28002e1a7c80bdaf9facb3559fad" + size 352338 provides (reftex-auc reftex-cite reftex-dcr reftex-vcr reftex-global reftex-index reftex-parse reftex-ref reftex-sel reftex-toc reftex-vars reftex) - requires (fsf-compat xemacs-base) + requires (xemacs-base) type regular )) )) @@ -1591,19 +1716,19 @@ (package-get-update-base-entry (quote (crisp (standards-version 1.1 - version "1.14" + version "1.15" author-version "1.34" - date "2003-10-31" - build-date "2003-10-31" + date "2005-04-26" + build-date "2005-04-26" maintainer "XEmacs Development Team " distribution xemacs priority low category "standard" dump nil description "Crisp/Brief emulation." - filename "crisp-1.14-pkg.tar.gz" - md5sum "ba1bbc29153b1849e71d123b9f2021b1" - size 10361 + filename "crisp-1.15-pkg.tar.gz" + md5sum "0efd73abddf2e032f520ed60b493d463" + size 10436 provides (crisp scroll-lock) requires () type regular @@ -1613,20 +1738,20 @@ (package-get-update-base-entry (quote (auctex (standards-version 1.1 - version "1.35" - author-version "11.13" - date "2003-01-03" - build-date "2003-01-03" - maintainer "XEmacs Development Team " + version "1.46" + author-version "11.55" + date "2005-02-12" + build-date "2005-12-08" + maintainer "Uwe Brauer " distribution xemacs priority medium category "standard" dump nil description "Basic TeX/LaTeX support." - filename "auctex-1.35-pkg.tar.gz" - md5sum "168e82155e152dab8c7c913bc9a4788b" - size 406466 - provides (auc-old auc-tex bib-cite font-latex latex multi-prompt tex-buf tex-info tex-jp tex-mik tex-site tex texmathp) + filename "auctex-1.46-pkg.tar.gz" + md5sum "0d7170230b9300fcef5eb57a7b4e6fbf" + size 710140 + provides (auc-old auc-tex bib-cite font-latex latex multi-prompt tex-buf tex-info tex-jp tex-mik tex-site tex texmathp hilit-LaTeX tex-font tex-fptex) requires (xemacs-base) type regular )) @@ -1635,19 +1760,19 @@ (package-get-update-base-entry (quote (vhdl (standards-version 1.1 - version "1.18" - author-version "3.31.20" - date "2003-10-31" - build-date "2003-10-31" + version "1.20" + author-version "3.33.2" + date "2005-02-14" + build-date "2005-02-14" maintainer "XEmacs Development Team " distribution xemacs priority low category "standard" dump nil description "Support for VHDL." - filename "vhdl-1.18-pkg.tar.gz" - md5sum "6a38f9e4428754114593b94089c71943" - size 273202 + filename "vhdl-1.20-pkg.tar.gz" + md5sum "f4f9381623e0c14957f2ea064e5044d5" + size 300258 provides (vhdl-mode) requires (xemacs-base edit-utils c-support speedbar ps-print os-utils) type regular @@ -1657,19 +1782,19 @@ (package-get-update-base-entry (quote (x-symbol (standards-version 1.1 - version "1.07" + version "1.10" author-version "4.5.1" - date "2003-10-26" - build-date "2003-10-26" - maintainer "Steve Youngs " + date "2004-02-16" + build-date "2004-02-16" + maintainer "Uwe Brauer " distribution xemacs priority high category "standard" dump nil description "Semi WYSIWYG for LaTeX, HTML, etc, using additional fonts." - filename "x-symbol-1.07-pkg.tar.gz" - md5sum "c4a1cfc1318d5eb87eb186f0972abad6" - size 679781 + filename "x-symbol-1.10-pkg.tar.gz" + md5sum "f213f93f156cc9eb511094292caf6f51" + size 680100 provides (x-symbol-bib x-symbol-hooks x-symbol-image x-symbol-macs x-symbol-mule x-symbol-nomule x-symbol-sgml x-symbol-tex x-symbol-texi x-symbol-vars x-symbol-xmacs x-symbol) requires (x-symbol xemacs-base auctex mail-lib) type regular @@ -1679,19 +1804,19 @@ (package-get-update-base-entry (quote (vc (standards-version 1.1 - version "1.38" + version "1.41" author-version "No-Upstream-Ver" - date "2003-10-27" - build-date "2003-10-27" + date "2005-06-05" + build-date "2005-06-05" maintainer "XEmacs Development Team " distribution xemacs priority low category "standard" dump nil description "Version Control for Free systems." - filename "vc-1.38-pkg.tar.gz" - md5sum "b19fa9b253ec9335829c3289ea1b046b" - size 93835 + filename "vc-1.41-pkg.tar.gz" + md5sum "78b4e9fefebd73d45e0953f719268d67" + size 94597 provides (vc vc-hooks) requires (dired xemacs-base vc mail-lib ediff) type regular @@ -1723,19 +1848,19 @@ (package-get-update-base-entry (quote (sh-script (standards-version 1.1 - version "1.18" - author-version "2.0e" - date "2003-10-31" - build-date "2003-10-31" + version "1.21" + author-version "2.0f" + date "2005-10-18" + build-date "2005-10-18" maintainer "XEmacs Development Team " distribution xemacs priority low category "standard" dump nil description "Support for editing shell scripts." - filename "sh-script-1.18-pkg.tar.gz" - md5sum "4a0e2de6d1006c987dfd9e861b8562cd" - size 37055 + filename "sh-script-1.21-pkg.tar.gz" + md5sum "c3cd67259af1073985af3d5ad83f4d2e" + size 70351 provides (sh-script executable) requires (xemacs-base) type regular @@ -1767,20 +1892,20 @@ (package-get-update-base-entry (quote (prog-modes (standards-version 1.1 - version "1.91" + version "2.06" author-version "No-Upstream-Ver" - date "2003-10-29" - build-date "2003-10-29" + date "2005-12-05" + build-date "2005-12-05" maintainer "XEmacs Development Team " distribution xemacs priority medium category "standard" dump nil description "Support for various programming languages." - filename "prog-modes-1.91-pkg.tar.gz" - md5sum "b0203d7e022fdf730845ffbceaf41bf0" - size 715961 - provides (autoconf-mode awk-mode c-mode cvs diff-mode eiffel-mode icon javascript-mode ksh-mode m4-mode make-mode makefile mode-compile mode-compile-kill modula2 p4 php-mode postscript rexx-mode rpm-spec-mode simula-mode sql tcl teco uil-mode verilog-mode) + filename "prog-modes-2.06-pkg.tar.gz" + md5sum "bf0e6a8a0ba1ad529fd945bc358b00c1" + size 777078 + provides (autoconf-mode awk-mode c-mode cvs diff-mode eiffel-mode icon javascript-mode ksh-mode lua-mode m4-mode make-mode makefile mode-compile mode-compile-kill modula2 p4 php-mode postscript rexx-mode rpm-spec-mode simula-mode sql tcl teco uil-mode verilog-mode) requires (mail-lib xemacs-devel xemacs-base cc-mode fsf-compat edit-utils ediff emerge efs vc speedbar dired ilisp sh-script) type regular )) @@ -1789,19 +1914,19 @@ (package-get-update-base-entry (quote (idlwave (standards-version 1.1 - version "1.31" + version "1.32" author-version "5.1" - date "2003-10-31" - build-date "2003-10-31" + date "2005-05-07" + build-date "2005-05-07" maintainer "Carsten Dominik " distribution xemacs priority medium category "standard" dump nil description "Editing and Shell mode for the Interactive Data Language" - filename "idlwave-1.31-pkg.tar.gz" - md5sum "c5e8e00757efddd5d83d9acb31247102" - size 520952 + filename "idlwave-1.32-pkg.tar.gz" + md5sum "3669f4554b9d1a487a5f3a279e5821e9" + size 520863 provides (idlw-rinfo idlwave-rinfo idlw-shell idlwave-shell idlw-toolbar idlwave-toolbar idlwave) requires (fsf-compat xemacs-base mail-lib) type regular @@ -1833,19 +1958,19 @@ (package-get-update-base-entry (quote (ediff (standards-version 1.1 - version "1.49" + version "1.60" author-version "2.75" - date "2003-10-31" - build-date "2003-10-31" + date "2005-12-05" + build-date "2005-12-05" maintainer "Michael Kifer " distribution xemacs priority medium category "standard" dump nil description "Interface over GNU patch." - filename "ediff-1.49-pkg.tar.gz" - md5sum "de66f77ac38f2df7dd4c5a94d9582f55" - size 305252 + filename "ediff-1.60-pkg.tar.gz" + md5sum "1c33606ab5bce3bf0a8c5f8fe949e2ca" + size 313973 provides (ediff-diff ediff-help ediff-hook ediff-init ediff-merg ediff-mult ediff-ptch ediff-tbar ediff-util ediff-vers ediff-wind ediff) requires (pcl-cvs elib dired xemacs-base edebug prog-modes) type regular @@ -1877,19 +2002,19 @@ (package-get-update-base-entry (quote (c-support (standards-version 1.1 - version "1.18" + version "1.22" author-version "No-Upstream-Ver" - date "2003-10-31" - build-date "2003-10-31" + date "2005-07-27" + build-date "2005-07-27" maintainer "XEmacs Development Team " distribution xemacs priority low category "standard" dump nil description "Basic single-file add-ons for editing C code." - filename "c-support-1.18-pkg.tar.gz" - md5sum "950c5d610fb614bd418863075cde1c4c" - size 70705 + filename "c-support-1.22-pkg.tar.gz" + md5sum "972b0abd7158053f28a2c66c62ce0270" + size 78027 provides (c-comment-edit cmacexp ctypes hideif hideshow) requires (cc-mode xemacs-base) type regular @@ -1921,19 +2046,19 @@ (package-get-update-base-entry (quote (cc-mode (standards-version 1.1 - version "1.41" - author-version "5.30.7" - date "2003-10-31" - build-date "2003-10-31" + version "1.45" + author-version "5.30.10" + date "2005-05-24" + build-date "2005-05-24" maintainer "Martin Stjernholm " distribution xemacs priority medium category "standard" dump nil description "C, C++, Objective-C, Java, CORBA IDL, Pike and AWK language support." - filename "cc-mode-1.41-pkg.tar.gz" - md5sum "31b9f8e38d95e6b5dd079c14f88ef360" - size 513369 + filename "cc-mode-1.45-pkg.tar.gz" + md5sum "e1a2e251e57f29ce6e082181c13c7f04" + size 524116 provides (cc-align cc-awk cc-bytecomp cc-cmds cc-compat cc-defs cc-engine cc-fix cc-fonts cc-guess cc-langs cc-lobotomy cc-menus cc-mode cc-styles cc-vars) requires (xemacs-base mail-lib) type regular @@ -1943,19 +2068,19 @@ (package-get-update-base-entry (quote (semantic (standards-version 1.1 - version "1.18" + version "1.19" author-version "1.4.2" - date "2003-10-31" - build-date "2003-10-31" + date "2004-10-31" + build-date "2004-10-31" maintainer "Eric M. Ludlam " distribution xemacs priority low category "standard" dump nil description "Semantic bovinator (Yacc/Lex for XEmacs). Includes Senator." - filename "semantic-1.18-pkg.tar.gz" - md5sum "bb333c47f371748a1e923893c98d7b3f" - size 443092 + filename "semantic-1.19-pkg.tar.gz" + md5sum "b7fdaa9ad2d2e9d9aaba5c88df8f2fd0" + size 446114 provides (document-vars document semantic-analyze semantic-bnf semantic-c semantic-cb semantic-chart semantic-ctxt semantic-el semantic-example semantic-ia-sb semantic-ia semantic-imenu semantic-java semantic-load semantic-make semantic-sb semantic-scm semantic-skel semantic-texi semantic-util-modes semantic-util semantic semanticdb senator sformat working) requires (eieio xemacs-base xemacs-devel edit-utils speedbar texinfo fsf-compat cc-mode edebug) type regular @@ -2009,19 +2134,19 @@ (package-get-update-base-entry (quote (games (standards-version 1.1 - version "1.15" + version "1.17" author-version "1.04" - date "2003-10-31" - build-date "2003-10-31" - maintainer "Glynn Clements " + date "2005-11-14" + build-date "2005-11-14" + maintainer "Glynn Clements " distribution xemacs priority low category "standard" dump nil description "Tetris, Sokoban, and Snake." - filename "games-1.15-pkg.tar.gz" - md5sum "e50c1cd9ae0e9d32a022f52e795119b4" - size 37242 + filename "games-1.17-pkg.tar.gz" + md5sum "42032b4568b5b46e588a6ffc63efd487" + size 37489 provides (gamegrid snake tetris sokoban) requires (xemacs-base) type regular @@ -2053,21 +2178,21 @@ (package-get-update-base-entry (quote (bbdb (standards-version 1.1 - version "1.24" + version "1.29" author-version "2.34" - date "2003-10-31" - build-date "2003-10-31" + date "2005-10-12" + build-date "2005-10-12" maintainer "Ronan Waide " distribution xemacs priority medium category "standard" dump nil description "The Big Brother Data Base" - filename "bbdb-1.24-pkg.tar.gz" - md5sum "bb9a7c33c742e28076643be7fda317ed" - size 373736 + filename "bbdb-1.29-pkg.tar.gz" + md5sum "c8314f305d41335ac91bf5a2ff10d635" + size 379982 provides (bbdb-com bbdb-ftp bbdb-gnus bbdb-gui bbdb-hooks bbdb-merge bbdb-mhe bbdb-migrate bbdb-print bbdb-reportmail bbdb-rmail bbdb-sc bbdb-snarf bbdb-srv bbdb-vm bbdb-w3 bbdb-whois bbdb-xemacs bbdb) - requires (bbdb edit-utils gnus mh-e rmail supercite vm tm apel mail-lib xemacs-base w3 fsf-compat eterm sh-script net-utils os-utils) + requires (bbdb edit-utils gnus mh-e rmail supercite vm tm apel mail-lib xemacs-base w3 fsf-compat eterm sh-script net-utils os-utils ecrypto) type regular )) )) @@ -2075,19 +2200,19 @@ (package-get-update-base-entry (quote (zenirc (standards-version 1.1 - version "1.14" + version "1.16" author-version "2.112" - date "2003-10-31" - build-date "2003-10-31" + date "2005-05-10" + build-date "2005-05-10" maintainer "XEmacs Development Team " distribution xemacs priority medium category "standard" dump nil description "ZENIRC IRC Client." - filename "zenirc-1.14-pkg.tar.gz" - md5sum "9e40efa659a867dae6aac4673b474322" - size 277304 + filename "zenirc-1.16-pkg.tar.gz" + md5sum "074e5d8aef2568e9e73bfb227faf61dd" + size 277377 provides (zenirc-18 zenirc-8ball zenirc-away zenirc-bork zenirc-color zenirc-command-queue zenirc-complete zenirc-ctcp-flood zenirc-dcc zenirc-doto zenirc-fill zenirc-finnish zenirc-format zenirc-fortran zenirc-french zenirc-history zenirc-ignore zenirc-iwantop zenirc-klingon zenirc-latin zenirc-meditate zenirc-netsplit zenirc-notify zenirc-oink zenirc-ojnk zenirc-pjg zenirc-popup zenirc-random-away zenirc-random-nick zenirc-signal zenirc-stamp zenirc-swedish zenirc-trigger zenirc-yow-filter zenirc-yow zenirc) requires (zenirc) type regular @@ -2097,19 +2222,19 @@ (package-get-update-base-entry (quote (mew (standards-version 1.1 - version "1.18" + version "1.19" author-version "1.94.2" - date "2003-10-31" - build-date "2003-10-31" + date "2005-05-10" + build-date "2005-05-10" maintainer "XEmacs Development Team " distribution xemacs priority low category "standard" dump nil description "Messaging in an Emacs World." - filename "mew-1.18-pkg.tar.gz" - md5sum "09533ddf67f0948c6b4a40b996d82fbd" - size 745829 + filename "mew-1.19-pkg.tar.gz" + md5sum "c3bad6f65dfc096c707ed238b138c940" + size 745714 provides (mew-addrbook mew-attach mew-bq mew-cache mew-complete mew-decode mew-demo mew-draft mew-encode mew-env mew-ext mew-fib mew-func mew-header mew-highlight mew-lang-jp mew-mark mew-message mew-mime mew-minibuf mew-mule mew-mule0 mew-mule2 mew-mule3 mew-os2 mew-pgp mew-pick mew-refile mew-scan mew-sort mew-summary mew-syntax mew-temacs mew-unix mew-vars mew-virtual mew-win32 mew-xemacs mew) requires (mew w3 efs mail-lib xemacs-base fsf-compat) type regular @@ -2119,21 +2244,21 @@ (package-get-update-base-entry (quote (tm (standards-version 1.1 - version "1.37" + version "1.38" author-version "No-Upstream-Ver" - date "2003-10-31" - build-date "2003-10-31" + date "2005-04-09" + build-date "2005-04-09" maintainer "XEmacs Development Team " distribution xemacs priority low category "standard" dump nil description "Emacs MIME support. Not needed for gnus >= 5.8.0" - filename "tm-1.37-pkg.tar.gz" - md5sum "9cd28b13243debe9a986dcbd332f1ccd" - size 334179 + filename "tm-1.38-pkg.tar.gz" + md5sum "dcf814b84cbe6cae01153ba702ccd704" + size 333864 provides (char-util cless gnus-art-mime gnus-charset gnus-mime gnus-sum-mime latex-math-symbol mel-b mel-g mel-q mel-u mel message-mime mime-setup mu-bbdb mu-cite range sc-setup signature texi-util tl-atype tl-list tl-misc tl-num tl-seq tl-str tm-bbdb tm-def tm-edit-mc tm-edit tm-ew-d tm-ew-e tm-file tm-ftp tm-html tm-image tm-latex tm-mail tm-mh-e tm-parse tm-partial tm-pgp tm-play tm-rmail tm-setup tm-tar tm-text tm-view tm-vm tmh-comp) - requires (gnus mh-e rmail vm mailcrypt mail-lib apel xemacs-base fsf-compat sh-script net-utils) + requires (gnus mh-e rmail vm mailcrypt mail-lib apel xemacs-base fsf-compat sh-script net-utils ecrypto) type regular )) )) @@ -2141,21 +2266,21 @@ (package-get-update-base-entry (quote (gnus (standards-version 1.1 - version "1.73" - author-version "5.10.2" - date "2003-10-13" - build-date "2003-10-13" - maintainer "Steve Youngs " + version "1.89" + author-version "5.10.7" + date "2006-01-04" + build-date "2006-01-04" + maintainer "Steve Youngs " distribution xemacs priority medium category "standard" dump nil description "The Gnus Newsreader and Mailreader." - filename "gnus-1.73-pkg.tar.gz" - md5sum "a1259caa28482a71bc4dfa1e434f9511" - size 3245188 + filename "gnus-1.89-pkg.tar.gz" + md5sum "e7707178416716eac643af29c437f619" + size 3457913 provides (binhex canlock compface deuglify earcon flow-fill format-spec gnus-agent gnus-art gnus-async gnus-audio gnus-bcklg gnus-cache gnus-cite gnus-cus gnus-delay gnus-demon gnus-diary gnus-dired gnus-draft gnus-dup gnus-eform gnus-ems gnus-fun gnus-gl gnus-group gnus-int gnus-kill gnus-logic gnus-mh gnus-ml gnus-mlspl gnus-move gnus-msg gnus-nocem gnus-picon gnus-range gnus-registry gnus-salt gnus-score gnus-setup gnus-sieve gnus-soup gnus-spec gnus-srvr gnus-start gnus-sum gnus-topic gnus-undo gnus-util gnus-uu gnus-vm gnus-win gnus-xmas gnus ietf-drums imap mail-parse mail-prsvr mail-source mailcap message messagexmas messcompat mm-bodies mm-decode mm-encode mm-extern mm-partial mm-url mm-util mm-uu mm-view mml-sec mml-smime mml mml1991 mml2015 nnagent nnbabyl nndb nndiary nndir nndoc nndraft nneething nnfolder nngateway nnheader nnheaderxm nnimap nnkiboze nnlistserv nnmail nnmaildir nnmbox nnmh nnml nnnil nnoo nnrss nnslashdot nnsoup nnspool nntp nnultimate nnvirtual nnwarchive nnweb nnwfm parse-time qp rfc1843 rfc2045 rfc2047 rfc2231 score-mode smiley smime spam-report spam-stat spam time-date utf7 uudecode webmail yenc gnus-idna gpg-ring gpg hashcash vcard) - requires (gnus w3 mh-e mailcrypt rmail eterm mail-lib xemacs-base fsf-compat ecrypto tm apel pgg net-utils sh-script os-utils dired sieve sasl) + requires (gnus mail-lib xemacs-base eterm sh-script net-utils os-utils dired mh-e sieve ps-print w3 pgg mailcrypt ecrypto sasl) type regular )) )) @@ -2185,19 +2310,19 @@ (package-get-update-base-entry (quote (mailcrypt (standards-version 1.1 - version "2.13" + version "2.14" author-version "3.5.8" - date "2003-10-31" - build-date "2003-10-31" + date "2004-01-17" + build-date "2004-01-17" maintainer "XEmacs Development Team " distribution xemacs priority low category "standard" dump nil description "Support for messaging encryption with PGP." - filename "mailcrypt-2.13-pkg.tar.gz" - md5sum "efe51870b559239cf48a102ea8a89e2f" - size 154111 + filename "mailcrypt-2.14-pkg.tar.gz" + md5sum "df1654138b6a146868bb52addb33bf47" + size 154180 provides (expect mailcrypt) requires (mail-lib fsf-compat xemacs-base cookie gnus mh-e rmail vm) type regular @@ -2207,19 +2332,19 @@ (package-get-update-base-entry (quote (supercite (standards-version 1.1 - version "1.20" + version "1.21" author-version "3.55x3" - date "2003-10-31" - build-date "2003-10-31" + date "2005-10-29" + build-date "2005-10-29" maintainer "XEmacs Development Team " distribution xemacs priority low category "standard" dump nil description "An Emacs citation tool for News & Mail messages." - filename "supercite-1.20-pkg.tar.gz" - md5sum "277fb688d3765c0434e34013e811e94d" - size 100553 + filename "supercite-1.21-pkg.tar.gz" + md5sum "4fb516d03f2d95d9e0e092c994f79df7" + size 100802 provides (supercite) requires (mail-lib xemacs-base) type regular @@ -2229,21 +2354,21 @@ (package-get-update-base-entry (quote (mh-e (standards-version 1.1 - version "1.27" + version "1.29" author-version "7.4.2" - date "2003-10-31" - build-date "2003-10-31" - maintainer "Steve Youngs " + date "2005-03-14" + build-date "2005-03-14" + maintainer "XEmacs Beta " distribution xemacs priority low category "standard" dump nil - description "Front end support for MH." - filename "mh-e-1.27-pkg.tar.gz" - md5sum "5b886efc6e93f97a61237dade2f360ee" - size 577724 + description "The XEmacs Interface to the MH Mail System." + filename "mh-e-1.29-pkg.tar.gz" + md5sum "c4009dbf4aa47d505dd8cb025e326ca3" + size 578385 provides (mh-alias mh-comp mh-customize mh-e mh-funcs mh-gnus mh-identity mh-inc mh-index mh-junk mh-loaddefs mh-mime mh-pick mh-seq mh-speed mh-unit mh-utils mh-xemacs-compat mh-xemacs-icons) - requires (gnus mail-lib xemacs-base speedbar rmail tm apel sh-script fsf-compat xemacs-devel net-utils eterm os-utils) + requires (gnus mail-lib xemacs-base speedbar rmail tm apel sh-script fsf-compat xemacs-devel net-utils eterm os-utils ecrypto) type regular )) )) @@ -2251,19 +2376,19 @@ (package-get-update-base-entry (quote (gnats (standards-version 1.1 - version "1.16" + version "1.17" author-version "3.101" - date "2003-10-31" - build-date "2003-10-31" + date "2005-04-09" + build-date "2005-04-09" maintainer "XEmacs Development Team " distribution xemacs priority high category "standard" dump nil description "XEmacs bug reports." - filename "gnats-1.16-pkg.tar.gz" - md5sum "678c190f7cd184426dcccc0f3a6d10b2" - size 188963 + filename "gnats-1.17-pkg.tar.gz" + md5sum "f048ff33f8b6f724613bd63173b9d9ef" + size 188959 provides (gnats gnats-admin send-pr) requires (mail-lib xemacs-base) type regular @@ -2317,21 +2442,23 @@ (package-get-update-base-entry (quote (net-utils (standards-version 1.1 - version "1.33" - author-version "No-Upstream-Ver" - date "2003-10-31" - build-date "2003-10-31" - maintainer "XEmacs Development Team " + version "1.48" + author-version "N/A" + date "2005-10-12" + build-date "2005-10-12" + maintainer "Steve Youngs " distribution xemacs priority low category "standard" dump nil description "Miscellaneous Networking Utilities." - filename "net-utils-1.33-pkg.tar.gz" - md5sum "9470e0dc21c8dd3c1d859ce7541f31c0" - size 137514 - provides (ilisp-browse-cltl2 xemacsbug feedmail metamail net-utils rcompile shadowfile webjump webster-www dig dns xml) - requires (bbdb w3 efs mail-lib xemacs-base fsf-compat eterm sh-script gnus rmail tm apel) + filename "net-utils-1.48-pkg.tar.gz" + md5sum "09cd58b37a72e17ff53c05ba1e67cf2f" + size 155120 + provides (ilisp-browse-cltl2 xemacsbug feedmail metamail + net-utils rcompile shadowfile webjump webster-www + dig dns dns-mode xml google-query mozmail) + requires (bbdb w3 efs mail-lib xemacs-base eterm sh-script gnus rmail tm apel vm mh-e mew ecrypto) type single )) )) @@ -2339,19 +2466,19 @@ (package-get-update-base-entry (quote (w3 (standards-version 1.1 - version "1.29" + version "1.32" author-version "4.0pre47" - date "2003-10-31" - build-date "2003-10-31" + date "2005-12-29" + build-date "2005-12-29" maintainer "XEmacs Development Team " distribution xemacs priority high category "standard" dump nil description "A Web browser." - filename "w3-1.29-pkg.tar.gz" - md5sum "088e276b855e95b2032aa58160ffeba2" - size 694178 + filename "w3-1.32-pkg.tar.gz" + md5sum "92a3dcd5c51317ab8317fe6059491213" + size 695310 provides (css devices w3-auto dsssl-flow dsssl font images mm mule-sysdp socks ssl urlauth url-cache url-cookie url-file url-gopher url-gw url-http url-ldap url-mail url-misc url-news url-ns url-parse url-vars url w3-about w3-auto w3-cfg w3-cus w3-display w3-emacs19 w3-e19 w3-e20 w3-elisp w3-emulate w3-forms w3-hot w3-hotindex w3-imap w3-java w3-jscript w3-keyword w3-latex w3-menu w3-mouse w3-parse w3-print w3-props w3-script w3-structure w3-speak w3-style w3-sysdp w3-toolbar w3-vars w3-widget w3-xemacs w3-xemac w3) requires (w3 mail-lib xemacs-base ecrypto) type regular @@ -2361,19 +2488,19 @@ (package-get-update-base-entry (quote (vm (standards-version 1.1 - version "7.18" + version "7.22" author-version "7.17" - date "2003-10-31" - build-date "2003-10-31" + date "2005-06-06" + build-date "2005-06-06" maintainer "Kyle Jones " distribution xemacs priority medium category "standard" dump nil description "An Emacs mailer." - filename "vm-7.18-pkg.tar.gz" - md5sum "25a353d78f64c2dd2e1001719158a315" - size 812340 + filename "vm-7.22-pkg.tar.gz" + md5sum "067b3cac6c8b6ee68a5fd2abf1e0acea" + size 822094 provides (tapestry vm-byteopts vm-delete vm-digest vm-easymenu vm-edit vm-folder vm-imap vm-license vm-macro vm-mark vm-menu vm-message vm-mime vm-minibuf vm-misc vm-motion vm-mouse vm-page vm-pop vm-reply vm-save vm-search vm-sort vm-startup vm-summary vm-thread vm-toolbar vm-undo vm-user vm-vars vm vm-version vm-virtual vm-window) requires (mail-lib xemacs-base) type regular @@ -2427,21 +2554,21 @@ (package-get-update-base-entry (quote (xemacs-devel (standards-version 1.1 - version "1.60" + version "1.72" author-version "No-Upstream-Ver" - date "2003-10-31" - build-date "2003-10-31" + date "2005-10-12" + build-date "2005-10-12" maintainer "XEmacs Development Team " distribution xemacs priority medium category "standard" dump nil description "Emacs Lisp developer support." - filename "xemacs-devel-1.60-pkg.tar.gz" - md5sum "db789317a15bf3a73bacd7b337ec7a34" - size 232116 + filename "xemacs-devel-1.72-pkg.tar.gz" + md5sum "b11f75c8ab895518f9324c668cb5fd84" + size 243274 provides (checkdoc docref eldoc elp eval-expr find-func hide-copyleft ielm patcher pp trace patch-keywords) - requires (xemacs-base ispell mail-lib gnus rmail tm apel sh-script net-utils eterm) + requires (xemacs-base ispell mail-lib gnus rmail tm apel sh-script net-utils eterm ecrypto) type single )) )) @@ -2493,21 +2620,21 @@ (package-get-update-base-entry (quote (edebug (standards-version 1.1 - version "1.20" + version "1.21" author-version "No-Upstream-Ver" - date "2003-10-31" - build-date "2003-10-31" + date "2004-07-05" + build-date "2004-07-05" maintainer "XEmacs Development Team " distribution xemacs priority low category "standard" dump nil description "An Emacs Lisp debugger." - filename "edebug-1.20-pkg.tar.gz" - md5sum "ff397fa7dba09ab0a52a83649b8a14d8" - size 115244 + filename "edebug-1.21-pkg.tar.gz" + md5sum "c3807d0c7bf76758b81f4d1837861758" + size 115585 provides (edebug cl-read cust-print eval-reg cl-specs) - requires (xemacs-base) + requires (xemacs-base xemacs-devel) type regular )) )) @@ -2515,19 +2642,19 @@ (package-get-update-base-entry (quote (Sun (standards-version 1.1 - version "1.15" + version "1.16" author-version "No-Upstream-Ver" - date "2003-10-31" - build-date "2003-10-31" + date "2004-09-06" + build-date "2004-09-06" maintainer "XEmacs Development Team " distribution xemacs priority low category "standard" dump nil description "Support for Sparcworks." - filename "Sun-1.15-pkg.tar.gz" - md5sum "ac4b09817681596ba032cf868c7c6dac" - size 64660 + filename "Sun-1.16-pkg.tar.gz" + md5sum "e82c814a75cab21586f81c6aef7d6ea9" + size 64431 provides (sccs eos-browser eos-common eos-debugger eos-debugger eos-editor eos-init eos-load eos-menubar eos-toolbar sunpro) requires (cc-mode xemacs-base) type regular @@ -2537,19 +2664,19 @@ (package-get-update-base-entry (quote (apel (standards-version 1.1 - version "1.27" - author-version "10.2" - date "2003-10-31" - build-date "2003-10-31" + version "1.32" + author-version "10.6" + date "2005-12-06" + build-date "2005-12-06" maintainer "XEmacs Development Team " distribution xemacs priority high category "standard" dump nil description "A Portable Emacs Library. Used by XEmacs MIME support." - filename "apel-1.27-pkg.tar.gz" - md5sum "2f35080836afe0730b2fe664f90b01be" - size 108585 + filename "apel-1.32-pkg.tar.gz" + md5sum "0c3f9d60d3bdaf4a7f4eaf2bdf656e84" + size 121589 provides (atype emu-20 emu-e19 emu-x20 emu-xemacs emu file-detect filename install mule-caesar path-util richtext std11-parse std11 tinyrich) requires (fsf-compat xemacs-base) type regular @@ -2559,19 +2686,19 @@ (package-get-update-base-entry (quote (efs (standards-version 1.0 - version "1.32" - author-version "1.22" - date "2003-10-31" - build-date "2003-10-31" + version "1.33" + author-version "1.23" + date "2004-10-04" + build-date "2004-10-04" maintainer "Mike Sperber " distribution stable priority medium category "standard" dump nil description "Treat files on remote systems the same as local files." - filename "efs-1.32-pkg.tar.gz" - md5sum "6123c11bc7a9c993429e9976f7bf42c4" - size 375800 + filename "efs-1.33-pkg.tar.gz" + md5sum "d0e7badb65439e1ac144aa4588be4db1" + size 375842 provides (efs) requires (xemacs-base dired) type regular @@ -2581,19 +2708,19 @@ (package-get-update-base-entry (quote (dired (standards-version 1.0 - version "1.15" - author-version "7.11" - date "2003-10-31" - build-date "2003-10-31" + version "1.17" + author-version "7.13" + date "2005-04-09" + build-date "2005-04-09" maintainer "Mike Sperber " distribution stable priority medium category "standard" dump nil description "Manage file systems." - filename "dired-1.15-pkg.tar.gz" - md5sum "3bd864d76ba88c2a8a42772222a2743f" - size 198282 + filename "dired-1.17-pkg.tar.gz" + md5sum "fc911843a2e768b657f61d4dc0137a6d" + size 201027 provides (diff dired) requires (xemacs-base prog-modes) type regular @@ -2602,10 +2729,9 @@ ;;;@@@ ;; Package Index file ends here -----BEGIN PGP SIGNATURE----- -Version: GnuPG v1.2.3 (FreeBSD) -Comment: The XEmacs Development Team +Version: GnuPG v1.4.1 (GNU/Linux) -iD4DBQE/s2HKgu3ywdHdhM0RAsIRAJiVkwgHSIPBMZBJlZdA06kOtKV2AKCqhmSb -/TUbeZRrIemjq9es9VqYJg== -=n9fY +iD8DBQFDu3/3gu3ywdHdhM0RArnQAKC2oQEX2BRllTlQl4UiMYIZYEBeQQCeNTHj +p3T7YxmbQDgZRUSOEEmtxs0= +=EoNd -----END PGP SIGNATURE----- diff -u -r -N xemacs-21.4.18/info/cl.info xemacs-21.4.19/info/cl.info --- xemacs-21.4.18/info/cl.info 1969-12-31 19:00:00.000000000 -0500 +++ xemacs-21.4.19/info/cl.info 2006-01-28 18:57:48.000000000 -0500 @@ -0,0 +1,5169 @@ +This is ../info/cl.info, produced by makeinfo version 4.8 from cl.texi. + +INFO-DIR-SECTION XEmacs Editor +START-INFO-DIR-ENTRY +* Common Lisp: (cl). GNU Emacs Common Lisp emulation package. +END-INFO-DIR-ENTRY + + This file documents the GNU Emacs Common Lisp emulation package. + + Copyright (C) 1993 Free Software Foundation, Inc. + + Permission is granted to make and distribute verbatim copies of this +manual provided the copyright notice and this permission notice are +preserved on all copies. + + Permission is granted to copy and distribute modified versions of +this manual under the conditions for verbatim copying, provided also +that the section entitled "GNU General Public License" is included +exactly as in the original, and provided that the entire resulting +derived work is distributed under the terms of a permission notice +identical to this one. + + Permission is granted to copy and distribute translations of this +manual into another language, under the above conditions for modified +versions, except that the section entitled "GNU General Public License" +may be included in a translation approved by the author instead of in +the original English. + + +File: cl.info, Node: Top, Next: Overview, Up: (dir) + +1 Common Lisp Extensions +************************ + +This document describes a set of Emacs Lisp facilities borrowed from +Common Lisp. All the facilities are described here in detail; for more +discussion and examples, Guy L. Steele's `Common Lisp, the Language', +second edition, is the definitive book on Common Lisp. While this +document does not assume any prior knowledge of Common Lisp, it does +assume a basic familiarity with Emacs Lisp. + +* Menu: + +* Overview:: Installation, usage, etc. +* Program Structure:: Arglists, `eval-when', `defalias' +* Predicates:: `typep', `eql', and `equalp' +* Control Structure:: `setf', `when', `do', `loop', etc. +* Macros:: Destructuring, `define-compiler-macro' +* Declarations:: `proclaim', `declare', etc. +* Symbols:: Property lists, `gensym' +* Numbers:: Predicates, functions, random numbers +* Sequences:: Mapping, functions, searching, sorting +* Lists:: `cadr', `sublis', `member*', `assoc*', etc. +* Hash Tables:: `make-hash-table', `gethash', etc. +* Structures:: `defstruct' +* Assertions:: `check-type', `assert', `ignore-errors'. + +* Efficiency Concerns:: Hints and techniques +* Common Lisp Compatibility:: All known differences with Steele +* Old CL Compatibility:: All known differences with old cl.el +* Porting Common Lisp:: Hints for porting Common Lisp code + +* Function Index:: +* Variable Index:: + + +File: cl.info, Node: Overview, Next: Program Structure, Prev: Top, Up: Top + +2 Overview +********** + +Common Lisp is a huge language, and Common Lisp systems tend to be +massive and extremely complex. Emacs Lisp, by contrast, is rather +minimalist in the choice of Lisp features it offers the programmer. As +Emacs Lisp programmers have grown in number, and the applications they +write have grown more ambitious, it has become clear that Emacs Lisp +could benefit from many of the conveniences of Common Lisp. + + The "CL" package adds a number of Common Lisp functions and control +structures to Emacs Lisp. While not a 100% complete implementation of +Common Lisp, "CL" adds enough functionality to make Emacs Lisp +programming significantly more convenient. + + Some Common Lisp features have been omitted from this package for +various reasons: + + * Some features are too complex or bulky relative to their benefit + to Emacs Lisp programmers. CLOS and Common Lisp streams are fine + examples of this group. + + * Other features cannot be implemented without modification to the + Emacs Lisp interpreter itself, such as multiple return values, + lexical scoping, case-insensitive symbols, and complex numbers. + The "CL" package generally makes no attempt to emulate these + features. + + * Some features conflict with existing things in Emacs Lisp. For + example, Emacs' `assoc' function is incompatible with the Common + Lisp `assoc'. In such cases, this package usually adds the suffix + `*' to the function name of the Common Lisp version of the + function (e.g., `assoc*'). + + The package described here was written by Dave Gillespie, +`daveg@synaptics.com'. It is a total rewrite of the original 1986 +`cl.el' package by Cesar Quiroz. Most features of the Quiroz package +have been retained; any incompatibilities are noted in the descriptions +below. Care has been taken in this version to ensure that each +function is defined efficiently, concisely, and with minimal impact on +the rest of the Emacs environment. + +* Menu: + +* Usage:: How to use the CL package +* Organization:: The package's five component files +* Installation:: Compiling and installing CL +* Naming Conventions:: Notes on CL function names + + +File: cl.info, Node: Usage, Next: Organization, Prev: Overview, Up: Overview + +2.1 Usage +========= + +Lisp code that uses features from the "CL" package should include at +the beginning: + + (require 'cl) + +If you want to ensure that the new (Gillespie) version of "CL" is the +one that is present, add an additional `(require 'cl-19)' call: + + (require 'cl) + (require 'cl-19) + +The second call will fail (with "`cl-19.el' not found") if the old +`cl.el' package was in use. + + It is safe to arrange to load "CL" at all times, e.g., in your +`.emacs' file. But it's a good idea, for portability, to `(require +'cl)' in your code even if you do this. + + +File: cl.info, Node: Organization, Next: Installation, Prev: Usage, Up: Overview + +2.2 Organization +================ + +The Common Lisp package is organized into four files: + +`cl.el' + This is the "main" file, which contains basic functions and + information about the package. This file is relatively + compact--about 700 lines. + +`cl-extra.el' + This file contains the larger, more complex or unusual functions. + It is kept separate so that packages which only want to use Common + Lisp fundamentals like the `cadr' function won't need to pay the + overhead of loading the more advanced functions. + +`cl-seq.el' + This file contains most of the advanced functions for operating on + sequences or lists, such as `delete-if' and `assoc*'. + +`cl-macs.el' + This file contains the features of the packages which are macros + instead of functions. Macros expand when the caller is compiled, + not when it is run, so the macros generally only need to be + present when the byte-compiler is running (or when the macros are + used in uncompiled code such as a `.emacs' file). Most of the + macros of this package are isolated in `cl-macs.el' so that they + won't take up memory unless you are compiling. + + The file `cl.el' includes all necessary `autoload' commands for the +functions and macros in the other three files. All you have to do is +`(require 'cl)', and `cl.el' will take care of pulling in the other +files when they are needed. + + There is another file, `cl-compat.el', which defines some routines +from the older `cl.el' package that are no longer present in the new +package. This includes internal routines like `setelt' and +`zip-lists', deprecated features like `defkeyword', and an emulation of +the old-style multiple-values feature. *Note Old CL Compatibility::. + + +File: cl.info, Node: Installation, Next: Naming Conventions, Prev: Organization, Up: Overview + +2.3 Installation +================ + +Installation of the "CL" package is simple: Just put the byte-compiled +files `cl.elc', `cl-extra.elc', `cl-seq.elc', `cl-macs.elc', and +`cl-compat.elc' into a directory on your `load-path'. + + There are no special requirements to compile this package: The files +do not have to be loaded before they are compiled, nor do they need to +be compiled in any particular order. + + You may choose to put the files into your main `lisp/' directory, +replacing the original `cl.el' file there. Or, you could put them into +a directory that comes before `lisp/' on your `load-path' so that the +old `cl.el' is effectively hidden. + + Also, format the `cl.texinfo' file and put the resulting Info files +in the `info/' directory or another suitable place. + + You may instead wish to leave this package's components all in their +own directory, and then add this directory to your `load-path' and +(Emacs 19 only) `Info-directory-list'. Add the directory to the front +of the list so the old "CL" package and its documentation are hidden. + + +File: cl.info, Node: Naming Conventions, Prev: Installation, Up: Overview + +2.4 Naming Conventions +====================== + +Except where noted, all functions defined by this package have the same +names and calling conventions as their Common Lisp counterparts. + + Following is a complete list of functions whose names were changed +from Common Lisp, usually to avoid conflicts with Emacs. In each case, +a `*' has been appended to the Common Lisp name to obtain the Emacs +name: + + defun* defsubst* defmacro* function* + member* assoc* rassoc* remove* + delete* mapcar* sort* floor* + ceiling* truncate* round* mod* + rem* random* + + Internal function and variable names in the package are prefixed by +`cl-'. Here is a complete list of functions _not_ prefixed by `cl-' +which were not taken from Common Lisp: + + member delete remove remq + rassoc floatp-safe lexical-let lexical-let* + callf callf2 letf letf* + defsubst* defalias add-hook eval-when-compile + +(Most of these are Emacs 19 features provided to Emacs 18 users, or +introduced, like `remq', for reasons of symmetry with similar features.) + + The following simple functions and macros are defined in `cl.el'; +they do not cause other components like `cl-extra' to be loaded. + + eql floatp-safe abs endp + evenp oddp plusp minusp + last butlast nbutlast caar .. cddddr + list* ldiff rest first .. tenth + member [1] copy-list subst mapcar* [2] + adjoin [3] acons pairlis when + unless pop [4] push [4] pushnew [3,4] + incf [4] decf [4] proclaim declaim + add-hook + +[1] This is the Emacs 19-compatible function, not `member*'. + +[2] Only for one sequence argument or two list arguments. + +[3] Only if `:test' is `eq', `equal', or unspecified, and `:key' is not +used. + +[4] Only when PLACE is a plain variable name. + + +File: cl.info, Node: Program Structure, Next: Predicates, Prev: Overview, Up: Top + +3 Program Structure +******************* + +This section describes features of the "CL" package which have to do +with programs as a whole: advanced argument lists for functions, and +the `eval-when' construct. + +* Menu: + +* Argument Lists:: `&key', `&aux', `defun*', `defmacro*'. +* Time of Evaluation:: The `eval-when' construct. +* Function Aliases:: The `defalias' function. + + +File: cl.info, Node: Argument Lists, Next: Time of Evaluation, Prev: Program Structure, Up: Program Structure + +3.1 Argument Lists +================== + +Emacs Lisp's notation for argument lists of functions is a subset of +the Common Lisp notation. As well as the familiar `&optional' and +`&rest' markers, Common Lisp allows you to specify default values for +optional arguments, and it provides the additional markers `&key' and +`&aux'. + + Since argument parsing is built-in to Emacs, there is no way for +this package to implement Common Lisp argument lists seamlessly. +Instead, this package defines alternates for several Lisp forms which +you must use if you need Common Lisp argument lists. + + -- Special Form: defun* name arglist body... + This form is identical to the regular `defun' form, except that + ARGLIST is allowed to be a full Common Lisp argument list. Also, + the function body is enclosed in an implicit block called NAME; + *note Blocks and Exits::. + + -- Special Form: defsubst* name arglist body... + This is just like `defun*', except that the function that is + defined is automatically proclaimed `inline', i.e., calls to it + may be expanded into in-line code by the byte compiler. This is + analogous to the `defsubst' form in Emacs 19; `defsubst*' uses a + different method (compiler macros) which works in all version of + Emacs, and also generates somewhat more efficient inline + expansions. In particular, `defsubst*' arranges for the + processing of keyword arguments, default values, etc., to be done + at compile-time whenever possible. + + -- Special Form: defmacro* name arglist body... + This is identical to the regular `defmacro' form, except that + ARGLIST is allowed to be a full Common Lisp argument list. The + `&environment' keyword is supported as described in Steele. The + `&whole' keyword is supported only within destructured lists (see + below); top-level `&whole' cannot be implemented with the current + Emacs Lisp interpreter. The macro expander body is enclosed in an + implicit block called NAME. + + -- Special Form: function* symbol-or-lambda + This is identical to the regular `function' form, except that if + the argument is a `lambda' form then that form may use a full + Common Lisp argument list. + + Also, all forms (such as `defsetf' and `flet') defined in this +package that include ARGLISTs in their syntax allow full Common Lisp +argument lists. + + Note that it is _not_ necessary to use `defun*' in order to have +access to most "CL" features in your function. These features are +always present; `defun*''s only difference from `defun' is its more +flexible argument lists and its implicit block. + + The full form of a Common Lisp argument list is + + (VAR... + &optional (VAR INITFORM SVAR)... + &rest VAR + &key ((KEYWORD VAR) INITFORM SVAR)... + &aux (VAR INITFORM)...) + + Each of the five argument list sections is optional. The SVAR, +INITFORM, and KEYWORD parts are optional; if they are omitted, then +`(VAR)' may be written simply `VAR'. + + The first section consists of zero or more "required" arguments. +These arguments must always be specified in a call to the function; +there is no difference between Emacs Lisp and Common Lisp as far as +required arguments are concerned. + + The second section consists of "optional" arguments. These +arguments may be specified in the function call; if they are not, +INITFORM specifies the default value used for the argument. (No +INITFORM means to use `nil' as the default.) The INITFORM is evaluated +with the bindings for the preceding arguments already established; `(a +&optional (b (1+ a)))' matches one or two arguments, with the second +argument defaulting to one plus the first argument. If the SVAR is +specified, it is an auxiliary variable which is bound to `t' if the +optional argument was specified, or to `nil' if the argument was +omitted. If you don't use an SVAR, then there will be no way for your +function to tell whether it was called with no argument, or with the +default value passed explicitly as an argument. + + The third section consists of a single "rest" argument. If more +arguments were passed to the function than are accounted for by the +required and optional arguments, those extra arguments are collected +into a list and bound to the "rest" argument variable. Common Lisp's +`&rest' is equivalent to that of Emacs Lisp. Common Lisp accepts +`&body' as a synonym for `&rest' in macro contexts; this package +accepts it all the time. + + The fourth section consists of "keyword" arguments. These are +optional arguments which are specified by name rather than positionally +in the argument list. For example, + + (defun* foo (a &optional b &key c d (e 17))) + +defines a function which may be called with one, two, or more +arguments. The first two arguments are bound to `a' and `b' in the +usual way. The remaining arguments must be pairs of the form `:c', +`:d', or `:e' followed by the value to be bound to the corresponding +argument variable. (Symbols whose names begin with a colon are called +"keywords", and they are self-quoting in the same way as `nil' and `t'.) + + For example, the call `(foo 1 2 :d 3 :c 4)' sets the five arguments +to 1, 2, 4, 3, and 17, respectively. If the same keyword appears more +than once in the function call, the first occurrence takes precedence +over the later ones. Note that it is not possible to specify keyword +arguments without specifying the optional argument `b' as well, since +`(foo 1 :c 2)' would bind `b' to the keyword `:c', then signal an error +because `2' is not a valid keyword. + + If a KEYWORD symbol is explicitly specified in the argument list as +shown in the above diagram, then that keyword will be used instead of +just the variable name prefixed with a colon. You can specify a +KEYWORD symbol which does not begin with a colon at all, but such +symbols will not be self-quoting; you will have to quote them +explicitly with an apostrophe in the function call. + + Ordinarily it is an error to pass an unrecognized keyword to a +function, e.g., `(foo 1 2 :c 3 :goober 4)'. You can ask Lisp to ignore +unrecognized keywords, either by adding the marker `&allow-other-keys' +after the keyword section of the argument list, or by specifying an +`:allow-other-keys' argument in the call whose value is non-`nil'. If +the function uses both `&rest' and `&key' at the same time, the "rest" +argument is bound to the keyword list as it appears in the call. For +example: + + (defun* find-thing (thing &rest rest &key need &allow-other-keys) + (or (apply 'member* thing thing-list :allow-other-keys t rest) + (if need (error "Thing not found")))) + +This function takes a `:need' keyword argument, but also accepts other +keyword arguments which are passed on to the `member*' function. +`allow-other-keys' is used to keep both `find-thing' and `member*' from +complaining about each others' keywords in the arguments. + + As a (significant) performance optimization, this package implements +the scan for keyword arguments by calling `memq' to search for keywords +in a "rest" argument. Technically speaking, this is incorrect, since +`memq' looks at the odd-numbered values as well as the even-numbered +keywords. The net effect is that if you happen to pass a keyword symbol +as the _value_ of another keyword argument, where that keyword symbol +happens to equal the name of a valid keyword argument of the same +function, then the keyword parser will become confused. This minor bug +can only affect you if you use keyword symbols as general-purpose data +in your program; this practice is strongly discouraged in Emacs Lisp. + + The fifth section of the argument list consists of "auxiliary +variables". These are not really arguments at all, but simply +variables which are bound to `nil' or to the specified INITFORMS during +execution of the function. There is no difference between the +following two functions, except for a matter of stylistic taste: + + (defun* foo (a b &aux (c (+ a b)) d) + BODY) + + (defun* foo (a b) + (let ((c (+ a b)) d) + BODY)) + + Argument lists support "destructuring". In Common Lisp, +destructuring is only allowed with `defmacro'; this package allows it +with `defun*' and other argument lists as well. In destructuring, any +argument variable (VAR in the above diagram) can be replaced by a list +of variables, or more generally, a recursive argument list. The +corresponding argument value must be a list whose elements match this +recursive argument list. For example: + + (defmacro* dolist ((var listform &optional resultform) + &rest body) + ...) + + This says that the first argument of `dolist' must be a list of two +or three items; if there are other arguments as well as this list, they +are stored in `body'. All features allowed in regular argument lists +are allowed in these recursive argument lists. In addition, the clause +`&whole VAR' is allowed at the front of a recursive argument list. It +binds VAR to the whole list being matched; thus `(&whole all a b)' +matches a list of two things, with `a' bound to the first thing, `b' +bound to the second thing, and `all' bound to the list itself. (Common +Lisp allows `&whole' in top-level `defmacro' argument lists as well, +but Emacs Lisp does not support this usage.) + + One last feature of destructuring is that the argument list may be +dotted, so that the argument list `(a b . c)' is functionally +equivalent to `(a b &rest c)'. + + If the optimization quality `safety' is set to 0 (*note +Declarations::), error checking for wrong number of arguments and +invalid keyword arguments is disabled. By default, argument lists are +rigorously checked. + + +File: cl.info, Node: Time of Evaluation, Next: Function Aliases, Prev: Argument Lists, Up: Program Structure + +3.2 Time of Evaluation +====================== + +Normally, the byte-compiler does not actually execute the forms in a +file it compiles. For example, if a file contains `(setq foo t)', the +act of compiling it will not actually set `foo' to `t'. This is true +even if the `setq' was a top-level form (i.e., not enclosed in a +`defun' or other form). Sometimes, though, you would like to have +certain top-level forms evaluated at compile-time. For example, the +compiler effectively evaluates `defmacro' forms at compile-time so that +later parts of the file can refer to the macros that are defined. + + -- Special Form: eval-when (situations...) forms... + This form controls when the body FORMS are evaluated. The + SITUATIONS list may contain any set of the symbols `compile', + `load', and `eval' (or their long-winded ANSI equivalents, + `:compile-toplevel', `:load-toplevel', and `:execute'). + + The `eval-when' form is handled differently depending on whether + or not it is being compiled as a top-level form. Specifically, it + gets special treatment if it is being compiled by a command such + as `byte-compile-file' which compiles files or buffers of code, + and it appears either literally at the top level of the file or + inside a top-level `progn'. + + For compiled top-level `eval-when's, the body FORMS are executed + at compile-time if `compile' is in the SITUATIONS list, and the + FORMS are written out to the file (to be executed at load-time) if + `load' is in the SITUATIONS list. + + For non-compiled-top-level forms, only the `eval' situation is + relevant. (This includes forms executed by the interpreter, forms + compiled with `byte-compile' rather than `byte-compile-file', and + non-top-level forms.) The `eval-when' acts like a `progn' if + `eval' is specified, and like `nil' (ignoring the body FORMS) if + not. + + The rules become more subtle when `eval-when's are nested; consult + Steele (second edition) for the gruesome details (and some + gruesome examples). + + Some simple examples: + + ;; Top-level forms in foo.el: + (eval-when (compile) (setq foo1 'bar)) + (eval-when (load) (setq foo2 'bar)) + (eval-when (compile load) (setq foo3 'bar)) + (eval-when (eval) (setq foo4 'bar)) + (eval-when (eval compile) (setq foo5 'bar)) + (eval-when (eval load) (setq foo6 'bar)) + (eval-when (eval compile load) (setq foo7 'bar)) + + When `foo.el' is compiled, these variables will be set during the + compilation itself: + + foo1 foo3 foo5 foo7 ; `compile' + + When `foo.elc' is loaded, these variables will be set: + + foo2 foo3 foo6 foo7 ; `load' + + And if `foo.el' is loaded uncompiled, these variables will be set: + + foo4 foo5 foo6 foo7 ; `eval' + + If these seven `eval-when's had been, say, inside a `defun', then + the first three would have been equivalent to `nil' and the last + four would have been equivalent to the corresponding `setq's. + + Note that `(eval-when (load eval) ...)' is equivalent to `(progn + ...)' in all contexts. The compiler treats certain top-level + forms, like `defmacro' (sort-of) and `require', as if they were + wrapped in `(eval-when (compile load eval) ...)'. + + Emacs 19 includes two special forms related to `eval-when'. One of +these, `eval-when-compile', is not quite equivalent to any `eval-when' +construct and is described below. This package defines a version of +`eval-when-compile' for the benefit of Emacs 18 users. + + The other form, `(eval-and-compile ...)', is exactly equivalent to +`(eval-when (compile load eval) ...)' and so is not itself defined by +this package. + + -- Special Form: eval-when-compile forms... + The FORMS are evaluated at compile-time; at execution time, this + form acts like a quoted constant of the resulting value. Used at + top-level, `eval-when-compile' is just like `eval-when (compile + eval)'. In other contexts, `eval-when-compile' allows code to be + evaluated once at compile-time for efficiency or other reasons. + + This form is similar to the `#.' syntax of true Common Lisp. + + -- Special Form: load-time-value form + The FORM is evaluated at load-time; at execution time, this form + acts like a quoted constant of the resulting value. + + Early Common Lisp had a `#,' syntax that was similar to this, but + ANSI Common Lisp replaced it with `load-time-value' and gave it + more well-defined semantics. + + In a compiled file, `load-time-value' arranges for FORM to be + evaluated when the `.elc' file is loaded and then used as if it + were a quoted constant. In code compiled by `byte-compile' rather + than `byte-compile-file', the effect is identical to + `eval-when-compile'. In uncompiled code, both `eval-when-compile' + and `load-time-value' act exactly like `progn'. + + (defun report () + (insert "This function was executed on: " + (current-time-string) + ", compiled on: " + (eval-when-compile (current-time-string)) + ;; or '#.(current-time-string) in real Common Lisp + ", and loaded on: " + (load-time-value (current-time-string)))) + + Byte-compiled, the above defun will result in the following code + (or its compiled equivalent, of course) in the `.elc' file: + + (setq --temp-- (current-time-string)) + (defun report () + (insert "This function was executed on: " + (current-time-string) + ", compiled on: " + '"Wed Jun 23 18:33:43 1993" + ", and loaded on: " + --temp--)) + + +File: cl.info, Node: Function Aliases, Prev: Time of Evaluation, Up: Program Structure + +3.3 Function Aliases +==================== + +This section describes a feature from GNU Emacs 19 which this package +makes available in other versions of Emacs. + + -- Function: defalias symbol function + This function sets SYMBOL's function cell to FUNCTION. It is + equivalent to `fset', except that in GNU Emacs 19 it also records + the setting in `load-history' so that it can be undone by a later + `unload-feature'. + + In other versions of Emacs, `defalias' is a synonym for `fset'. + + +File: cl.info, Node: Predicates, Next: Control Structure, Prev: Program Structure, Up: Top + +4 Predicates +************ + +This section describes functions for testing whether various facts are +true or false. + +* Menu: + +* Type Predicates:: `typep', `deftype', and `coerce' +* Equality Predicates:: `eql' and `equalp' + + +File: cl.info, Node: Type Predicates, Next: Equality Predicates, Prev: Predicates, Up: Predicates + +4.1 Type Predicates +=================== + +The "CL" package defines a version of the Common Lisp `typep' predicate. + + -- Function: typep object type + Check if OBJECT is of type TYPE, where TYPE is a (quoted) type + name of the sort used by Common Lisp. For example, `(typep foo + 'integer)' is equivalent to `(integerp foo)'. + + The TYPE argument to the above function is either a symbol or a list +beginning with a symbol. + + * If the type name is a symbol, Emacs appends `-p' to the symbol + name to form the name of a predicate function for testing the + type. (Built-in predicates whose names end in `p' rather than + `-p' are used when appropriate.) + + * The type symbol `t' stands for the union of all types. `(typep + OBJECT t)' is always true. Likewise, the type symbol `nil' stands + for nothing at all, and `(typep OBJECT nil)' is always false. + + * The type symbol `null' represents the symbol `nil'. Thus `(typep + OBJECT 'null)' is equivalent to `(null OBJECT)'. + + * The type symbol `real' is a synonym for `number', and `fixnum' is + a synonym for `integer'. + + * The type symbols `character' and `string-char' match characters. + In Emacs-19 and XEmacs-19, characters are the same thing as + integers in the range 0-255. In XEmacs-20, where characters are a + first-class data type, this checks for actual characters, and + `(typep 8BIT-INTEGER 'character)' will return `nil'. + + * The type symbol `float' uses the `floatp-safe' predicate defined + by this package rather than `floatp', so it will work correctly + even in Emacs versions without floating-point support. + + * The type list `(integer LOW HIGH)' represents all integers between + LOW and HIGH, inclusive. Either bound may be a list of a single + integer to specify an exclusive limit, or a `*' to specify no + limit. The type `(integer * *)' is thus equivalent to `integer'. + + * Likewise, lists beginning with `float', `real', or `number' + represent numbers of that type falling in a particular range. + + * Lists beginning with `and', `or', and `not' form combinations of + types. For example, `(or integer (float 0 *))' represents all + objects that are integers or non-negative floats. + + * Lists beginning with `member' or `member*' represent objects `eql' + to any of the following values. For example, `(member 1 2 3 4)' + is equivalent to `(integer 1 4)', and `(member nil)' is equivalent + to `null'. + + * Lists of the form `(satisfies PREDICATE)' represent all objects + for which PREDICATE returns true when called with that object as + an argument. + + The following function and macro (not technically predicates) are +related to `typep'. + + -- Function: coerce object type + This function attempts to convert OBJECT to the specified TYPE. + If OBJECT is already of that type as determined by `typep', it is + simply returned. Otherwise, certain types of conversions will be + made: If TYPE is any sequence type (`string', `list', etc.) then + OBJECT will be converted to that type if possible. If TYPE is + `character', then strings of length one and symbols with + one-character names can be coerced. If TYPE is `float', then + integers can be coerced in versions of Emacs that support floats. + In all other circumstances, `coerce' signals an error. + + -- Special Form: deftype name arglist forms... + This macro defines a new type called NAME. It is similar to + `defmacro' in many ways; when NAME is encountered as a type name, + the body FORMS are evaluated and should return a type specifier + that is equivalent to the type. The ARGLIST is a Common Lisp + argument list of the sort accepted by `defmacro*'. The type + specifier `(NAME ARGS...)' is expanded by calling the expander + with those arguments; the type symbol `NAME' is expanded by + calling the expander with no arguments. The ARGLIST is processed + the same as for `defmacro*' except that optional arguments without + explicit defaults use `*' instead of `nil' as the "default" + default. Some examples: + + (deftype null () '(satisfies null)) ; predefined + (deftype list () '(or null cons)) ; predefined + (deftype unsigned-byte (&optional bits) + (list 'integer 0 (if (eq bits '*) bits (1- (lsh 1 bits))))) + (unsigned-byte 8) == (integer 0 255) + (unsigned-byte) == (integer 0 *) + unsigned-byte == (integer 0 *) + + The last example shows how the Common Lisp `unsigned-byte' type + specifier could be implemented if desired; this package does not + implement `unsigned-byte' by default. + + The `typecase' and `check-type' macros also use type names. *Note +Conditionals::. *Note Assertions::. The `map', `concatenate', and +`merge' functions take type-name arguments to specify the type of +sequence to return. *Note Sequences::. + + +File: cl.info, Node: Equality Predicates, Prev: Type Predicates, Up: Predicates + +4.2 Equality Predicates +======================= + +This package defines two Common Lisp predicates, `eql' and `equalp'. + + -- Function: eql a b + This function is almost the same as `eq', except that if A and B + are numbers of the same type, it compares them for numeric + equality (as if by `equal' instead of `eq'). This makes a + difference only for versions of Emacs that are compiled with + floating-point support, such as Emacs 19. Emacs floats are + allocated objects just like cons cells, which means that `(eq 3.0 + 3.0)' will not necessarily be true--if the two `3.0's were + allocated separately, the pointers will be different even though + the numbers are the same. But `(eql 3.0 3.0)' will always be true. + + The types of the arguments must match, so `(eql 3 3.0)' is still + false. + + Note that Emacs integers are "direct" rather than allocated, which + basically means `(eq 3 3)' will always be true. Thus `eq' and + `eql' behave differently only if floating-point numbers are + involved, and are indistinguishable on Emacs versions that don't + support floats. + + There is a slight inconsistency with Common Lisp in the treatment + of positive and negative zeros. Some machines, notably those with + IEEE standard arithmetic, represent `+0' and `-0' as distinct + values. Normally this doesn't matter because the standard + specifies that `(= 0.0 -0.0)' should always be true, and this is + indeed what Emacs Lisp and Common Lisp do. But the Common Lisp + standard states that `(eql 0.0 -0.0)' and `(equal 0.0 -0.0)' should + be false on IEEE-like machines; Emacs Lisp does not do this, and in + fact the only known way to distinguish between the two zeros in + Emacs Lisp is to `format' them and check for a minus sign. + + -- Function: equalp a b + This function is a more flexible version of `equal'. In + particular, it compares strings and characters case-insensitively, + and it compares numbers without regard to type (so that `(equalp 3 + 3.0)' is true). Vectors and conses are compared recursively. All + other objects are compared as if by `equal'. + + This function differs from Common Lisp `equalp' in several + respects. In keeping with the idea that strings are less + vector-like in Emacs Lisp, this package's `equalp' also will not + compare strings against vectors of integers. + + Also note that the Common Lisp functions `member' and `assoc' use +`eql' to compare elements, whereas Emacs Lisp follows the MacLisp +tradition and uses `equal' for these two functions. In Emacs, use +`member*' and `assoc*' to get functions which use `eql' for comparisons. + + +File: cl.info, Node: Control Structure, Next: Macros, Prev: Predicates, Up: Top + +5 Control Structure +******************* + +The features described in the following sections implement various +advanced control structures, including the powerful `setf' facility and +a number of looping and conditional constructs. + +* Menu: + +* Assignment:: The `psetq' form +* Generalized Variables:: `setf', `incf', `push', etc. +* Variable Bindings:: `progv', `lexical-let', `flet', `macrolet' +* Conditionals:: `when', `unless', `case', `typecase' +* Blocks and Exits:: `block', `return', `return-from' +* Iteration:: `do', `dotimes', `dolist', `do-symbols' +* Loop Facility:: The Common Lisp `loop' macro +* Multiple Values:: `values', `multiple-value-bind', etc. + + +File: cl.info, Node: Assignment, Next: Generalized Variables, Prev: Control Structure, Up: Control Structure + +5.1 Assignment +============== + +The `psetq' form is just like `setq', except that multiple assignments +are done in parallel rather than sequentially. + + -- Special Form: psetq [symbol form]... + This special form (actually a macro) is used to assign to several + variables simultaneously. Given only one SYMBOL and FORM, it has + the same effect as `setq'. Given several SYMBOL and FORM pairs, + it evaluates all the FORMs in advance and then stores the + corresponding variables afterwards. + + (setq x 2 y 3) + (setq x (+ x y) y (* x y)) + x + => 5 + y ; `y' was computed after `x' was set. + => 15 + (setq x 2 y 3) + (psetq x (+ x y) y (* x y)) + x + => 5 + y ; `y' was computed before `x' was set. + => 6 + + The simplest use of `psetq' is `(psetq x y y x)', which exchanges + the values of two variables. (The `rotatef' form provides an even + more convenient way to swap two variables; *note Modify Macros::.) + + `psetq' always returns `nil'. + + +File: cl.info, Node: Generalized Variables, Next: Variable Bindings, Prev: Assignment, Up: Control Structure + +5.2 Generalized Variables +========================= + +A "generalized variable" or "place form" is one of the many places in +Lisp memory where values can be stored. The simplest place form is a +regular Lisp variable. But the cars and cdrs of lists, elements of +arrays, properties of symbols, and many other locations are also places +where Lisp values are stored. + + The `setf' form is like `setq', except that it accepts arbitrary +place forms on the left side rather than just symbols. For example, +`(setf (car a) b)' sets the car of `a' to `b', doing the same operation +as `(setcar a b)' but without having to remember two separate functions +for setting and accessing every type of place. + + Generalized variables are analogous to "lvalues" in the C language, +where `x = a[i]' gets an element from an array and `a[i] = x' stores an +element using the same notation. Just as certain forms like `a[i]' can +be lvalues in C, there is a set of forms that can be generalized +variables in Lisp. + +* Menu: + +* Basic Setf:: `setf' and place forms +* Modify Macros:: `incf', `push', `rotatef', `letf', `callf', etc. +* Customizing Setf:: `define-modify-macro', `defsetf', `define-setf-method' + + +File: cl.info, Node: Basic Setf, Next: Modify Macros, Prev: Generalized Variables, Up: Generalized Variables + +5.2.1 Basic Setf +---------------- + +The `setf' macro is the most basic way to operate on generalized +variables. + + -- Special Form: setf [place form]... + This macro evaluates FORM and stores it in PLACE, which must be a + valid generalized variable form. If there are several PLACE and + FORM pairs, the assignments are done sequentially just as with + `setq'. `setf' returns the value of the last FORM. + + The following Lisp forms will work as generalized variables, and + so may legally appear in the PLACE argument of `setf': + + * A symbol naming a variable. In other words, `(setf x y)' is + exactly equivalent to `(setq x y)', and `setq' itself is + strictly speaking redundant now that `setf' exists. Many + programmers continue to prefer `setq' for setting simple + variables, though, purely for stylistic or historical reasons. + The form `(setf x y)' actually expands to `(setq x y)', so + there is no performance penalty for using it in compiled code. + + * A call to any of the following Lisp functions: + + car cdr caar .. cddddr + nth rest first .. tenth + aref elt nthcdr + symbol-function symbol-value symbol-plist + get getf gethash + subseq + + Note that for `nthcdr' and `getf', the list argument of the + function must itself be a valid PLACE form. For example, + `(setf (nthcdr 0 foo) 7)' will set `foo' itself to 7. Note + that `push' and `pop' on an `nthcdr' place can be used to + insert or delete at any position in a list. The use of + `nthcdr' as a PLACE form is an extension to standard Common + Lisp. + + * The following Emacs-specific functions are also `setf'-able. + (Some of these are defined only in Emacs 19 or only in + XEmacs.) + + buffer-file-name marker-position + buffer-modified-p match-data + buffer-name mouse-position + buffer-string overlay-end + buffer-substring overlay-get + current-buffer overlay-start + current-case-table point + current-column point-marker + current-global-map point-max + current-input-mode point-min + current-local-map process-buffer + current-window-configuration process-filter + default-file-modes process-sentinel + default-value read-mouse-position + documentation-property screen-height + extent-data screen-menubar + extent-end-position screen-width + extent-start-position selected-window + face-background selected-screen + face-background-pixmap selected-frame + face-font standard-case-table + face-foreground syntax-table + face-underline-p window-buffer + file-modes window-dedicated-p + frame-height window-display-table + frame-parameters window-height + frame-visible-p window-hscroll + frame-width window-point + get-register window-start + getenv window-width + global-key-binding x-get-cut-buffer + keymap-parent x-get-cutbuffer + local-key-binding x-get-secondary-selection + mark x-get-selection + mark-marker + + Most of these have directly corresponding "set" functions, + like `use-local-map' for `current-local-map', or `goto-char' + for `point'. A few, like `point-min', expand to longer + sequences of code when they are `setf''d (`(narrow-to-region + x (point-max))' in this case). + + * A call of the form `(substring SUBPLACE N [M])', where + SUBPLACE is itself a legal generalized variable whose current + value is a string, and where the value stored is also a + string. The new string is spliced into the specified part of + the destination string. For example: + + (setq a (list "hello" "world")) + => ("hello" "world") + (cadr a) + => "world" + (substring (cadr a) 2 4) + => "rl" + (setf (substring (cadr a) 2 4) "o") + => "o" + (cadr a) + => "wood" + a + => ("hello" "wood") + + The generalized variable `buffer-substring', listed above, + also works in this way by replacing a portion of the current + buffer. + + * A call of the form `(apply 'FUNC ...)' or `(apply (function + FUNC) ...)', where FUNC is a `setf'-able function whose store + function is "suitable" in the sense described in Steele's + book; since none of the standard Emacs place functions are + suitable in this sense, this feature is only interesting when + used with places you define yourself with + `define-setf-method' or the long form of `defsetf'. + + * A macro call, in which case the macro is expanded and `setf' + is applied to the resulting form. + + * Any form for which a `defsetf' or `define-setf-method' has + been made. + + Using any forms other than these in the PLACE argument to `setf' + will signal an error. + + The `setf' macro takes care to evaluate all subforms in the proper + left-to-right order; for example, + + (setf (aref vec (incf i)) i) + + looks like it will evaluate `(incf i)' exactly once, before the + following access to `i'; the `setf' expander will insert temporary + variables as necessary to ensure that it does in fact work this + way no matter what setf-method is defined for `aref'. (In this + case, `aset' would be used and no such steps would be necessary + since `aset' takes its arguments in a convenient order.) + + However, if the PLACE form is a macro which explicitly evaluates + its arguments in an unusual order, this unusual order will be + preserved. Adapting an example from Steele, given + + (defmacro wrong-order (x y) (list 'aref y x)) + + the form `(setf (wrong-order A B) 17)' will evaluate B first, then + A, just as in an actual call to `wrong-order'. + + +File: cl.info, Node: Modify Macros, Next: Customizing Setf, Prev: Basic Setf, Up: Generalized Variables + +5.2.2 Modify Macros +------------------- + +This package defines a number of other macros besides `setf' that +operate on generalized variables. Many are interesting and useful even +when the PLACE is just a variable name. + + -- Special Form: psetf [place form]... + This macro is to `setf' what `psetq' is to `setq': When several + PLACEs and FORMs are involved, the assignments take place in + parallel rather than sequentially. Specifically, all subforms are + evaluated from left to right, then all the assignments are done + (in an undefined order). + + -- Special Form: incf place &optional x + This macro increments the number stored in PLACE by one, or by X + if specified. The incremented value is returned. For example, + `(incf i)' is equivalent to `(setq i (1+ i))', and `(incf (car x) + 2)' is equivalent to `(setcar x (+ (car x) 2))'. + + Once again, care is taken to preserve the "apparent" order of + evaluation. For example, + + (incf (aref vec (incf i))) + + appears to increment `i' once, then increment the element of `vec' + addressed by `i'; this is indeed exactly what it does, which means + the above form is _not_ equivalent to the "obvious" expansion, + + (setf (aref vec (incf i)) (1+ (aref vec (incf i)))) ; Wrong! + + but rather to something more like + + (let ((temp (incf i))) + (setf (aref vec temp) (1+ (aref vec temp)))) + + Again, all of this is taken care of automatically by `incf' and + the other generalized-variable macros. + + As a more Emacs-specific example of `incf', the expression `(incf + (point) N)' is essentially equivalent to `(forward-char N)'. + + -- Special Form: decf place &optional x + This macro decrements the number stored in PLACE by one, or by X + if specified. + + -- Special Form: pop place + This macro removes and returns the first element of the list stored + in PLACE. It is analogous to `(prog1 (car PLACE) (setf PLACE (cdr + PLACE)))', except that it takes care to evaluate all subforms only + once. + + -- Special Form: push x place + This macro inserts X at the front of the list stored in PLACE. It + is analogous to `(setf PLACE (cons X PLACE))', except for + evaluation of the subforms. + + -- Special Form: pushnew x place &key :test :test-not :key + This macro inserts X at the front of the list stored in PLACE, but + only if X was not `eql' to any existing element of the list. The + optional keyword arguments are interpreted in the same way as for + `adjoin'. *Note Lists as Sets::. + + -- Special Form: shiftf place... newvalue + This macro shifts the PLACEs left by one, shifting in the value of + NEWVALUE (which may be any Lisp expression, not just a generalized + variable), and returning the value shifted out of the first PLACE. + Thus, `(shiftf A B C D)' is equivalent to + + (prog1 + A + (psetf A B + B C + C D)) + + except that the subforms of A, B, and C are actually evaluated + only once each and in the apparent order. + + -- Special Form: rotatef place... + This macro rotates the PLACEs left by one in circular fashion. + Thus, `(rotatef A B C D)' is equivalent to + + (psetf A B + B C + C D + D A) + + except for the evaluation of subforms. `rotatef' always returns + `nil'. Note that `(rotatef A B)' conveniently exchanges A and B. + + The following macros were invented for this package; they have no +analogues in Common Lisp. + + -- Special Form: letf (bindings...) forms... + This macro is analogous to `let', but for generalized variables + rather than just symbols. Each BINDING should be of the form + `(PLACE VALUE)'; the original contents of the PLACEs are saved, + the VALUEs are stored in them, and then the body FORMs are + executed. Afterwards, the PLACES are set back to their original + saved contents. This cleanup happens even if the FORMs exit + irregularly due to a `throw' or an error. + + For example, + + (letf (((point) (point-min)) + (a 17)) + ...) + + moves "point" in the current buffer to the beginning of the buffer, + and also binds `a' to 17 (as if by a normal `let', since `a' is + just a regular variable). After the body exits, `a' is set back + to its original value and point is moved back to its original + position. + + Note that `letf' on `(point)' is not quite like a + `save-excursion', as the latter effectively saves a marker which + tracks insertions and deletions in the buffer. Actually, a `letf' + of `(point-marker)' is much closer to this behavior. (`point' and + `point-marker' are equivalent as `setf' places; each will accept + either an integer or a marker as the stored value.) + + Since generalized variables look like lists, `let''s shorthand of + using `foo' for `(foo nil)' as a BINDING would be ambiguous in + `letf' and is not allowed. + + However, a BINDING specifier may be a one-element list `(PLACE)', + which is similar to `(PLACE PLACE)'. In other words, the PLACE is + not disturbed on entry to the body, and the only effect of the + `letf' is to restore the original value of PLACE afterwards. (The + redundant access-and-store suggested by the `(PLACE PLACE)' + example does not actually occur.) + + In most cases, the PLACE must have a well-defined value on entry + to the `letf' form. The only exceptions are plain variables and + calls to `symbol-value' and `symbol-function'. If the symbol is + not bound on entry, it is simply made unbound by `makunbound' or + `fmakunbound' on exit. + + -- Special Form: letf* (bindings...) forms... + This macro is to `letf' what `let*' is to `let': It does the + bindings in sequential rather than parallel order. + + -- Special Form: callf FUNCTION PLACE ARGS... + This is the "generic" modify macro. It calls FUNCTION, which + should be an unquoted function name, macro name, or lambda. It + passes PLACE and ARGS as arguments, and assigns the result back to + PLACE. For example, `(incf PLACE N)' is the same as `(callf + + PLACE N)'. Some more examples: + + (callf abs my-number) + (callf concat (buffer-name) "<" (int-to-string n) ">") + (callf union happy-people (list joe bob) :test 'same-person) + + *Note Customizing Setf::, for `define-modify-macro', a way to + create even more concise notations for modify macros. Note again + that `callf' is an extension to standard Common Lisp. + + -- Special Form: callf2 FUNCTION ARG1 PLACE ARGS... + This macro is like `callf', except that PLACE is the _second_ + argument of FUNCTION rather than the first. For example, `(push X + PLACE)' is equivalent to `(callf2 cons X PLACE)'. + + The `callf' and `callf2' macros serve as building blocks for other +macros like `incf', `pushnew', and `define-modify-macro'. The `letf' +and `letf*' macros are used in the processing of symbol macros; *note +Macro Bindings::. + + +File: cl.info, Node: Customizing Setf, Prev: Modify Macros, Up: Generalized Variables + +5.2.3 Customizing Setf +---------------------- + +Common Lisp defines three macros, `define-modify-macro', `defsetf', and +`define-setf-method', that allow the user to extend generalized +variables in various ways. + + -- Special Form: define-modify-macro name arglist function [doc-string] + This macro defines a "read-modify-write" macro similar to `incf' + and `decf'. The macro NAME is defined to take a PLACE argument + followed by additional arguments described by ARGLIST. The call + + (NAME PLACE ARGS...) + + will be expanded to + + (callf FUNC PLACE ARGS...) + + which in turn is roughly equivalent to + + (setf PLACE (FUNC PLACE ARGS...)) + + For example: + + (define-modify-macro incf (&optional (n 1)) +) + (define-modify-macro concatf (&rest args) concat) + + Note that `&key' is not allowed in ARGLIST, but `&rest' is + sufficient to pass keywords on to the function. + + Most of the modify macros defined by Common Lisp do not exactly + follow the pattern of `define-modify-macro'. For example, `push' + takes its arguments in the wrong order, and `pop' is completely + irregular. You can define these macros "by hand" using + `get-setf-method', or consult the source file `cl-macs.el' to see + how to use the internal `setf' building blocks. + + -- Special Form: defsetf access-fn update-fn + This is the simpler of two `defsetf' forms. Where ACCESS-FN is + the name of a function which accesses a place, this declares + UPDATE-FN to be the corresponding store function. From now on, + + (setf (ACCESS-FN ARG1 ARG2 ARG3) VALUE) + + will be expanded to + + (UPDATE-FN ARG1 ARG2 ARG3 VALUE) + + The UPDATE-FN is required to be either a true function, or a macro + which evaluates its arguments in a function-like way. Also, the + UPDATE-FN is expected to return VALUE as its result. Otherwise, + the above expansion would not obey the rules for the way `setf' is + supposed to behave. + + As a special (non-Common-Lisp) extension, a third argument of `t' + to `defsetf' says that the `update-fn''s return value is not + suitable, so that the above `setf' should be expanded to something + more like + + (let ((temp VALUE)) + (UPDATE-FN ARG1 ARG2 ARG3 temp) + temp) + + Some examples of the use of `defsetf', drawn from the standard + suite of setf methods, are: + + (defsetf car setcar) + (defsetf symbol-value set) + (defsetf buffer-name rename-buffer t) + + -- Special Form: defsetf access-fn arglist (store-var) forms... + This is the second, more complex, form of `defsetf'. It is rather + like `defmacro' except for the additional STORE-VAR argument. The + FORMS should return a Lisp form which stores the value of + STORE-VAR into the generalized variable formed by a call to + ACCESS-FN with arguments described by ARGLIST. The FORMS may + begin with a string which documents the `setf' method (analogous + to the doc string that appears at the front of a function). + + For example, the simple form of `defsetf' is shorthand for + + (defsetf ACCESS-FN (&rest args) (store) + (append '(UPDATE-FN) args (list store))) + + The Lisp form that is returned can access the arguments from + ARGLIST and STORE-VAR in an unrestricted fashion; macros like + `setf' and `incf' which invoke this setf-method will insert + temporary variables as needed to make sure the apparent order of + evaluation is preserved. + + Another example drawn from the standard package: + + (defsetf nth (n x) (store) + (list 'setcar (list 'nthcdr n x) store)) + + -- Special Form: define-setf-method access-fn arglist forms... + This is the most general way to create new place forms. When a + `setf' to ACCESS-FN with arguments described by ARGLIST is + expanded, the FORMS are evaluated and must return a list of five + items: + + 1. A list of "temporary variables". + + 2. A list of "value forms" corresponding to the temporary + variables above. The temporary variables will be bound to + these value forms as the first step of any operation on the + generalized variable. + + 3. A list of exactly one "store variable" (generally obtained + from a call to `gensym'). + + 4. A Lisp form which stores the contents of the store variable + into the generalized variable, assuming the temporaries have + been bound as described above. + + 5. A Lisp form which accesses the contents of the generalized + variable, assuming the temporaries have been bound. + + This is exactly like the Common Lisp macro of the same name, + except that the method returns a list of five values rather than + the five values themselves, since Emacs Lisp does not support + Common Lisp's notion of multiple return values. + + Once again, the FORMS may begin with a documentation string. + + A setf-method should be maximally conservative with regard to + temporary variables. In the setf-methods generated by `defsetf', + the second return value is simply the list of arguments in the + place form, and the first return value is a list of a + corresponding number of temporary variables generated by `gensym'. + Macros like `setf' and `incf' which use this setf-method will + optimize away most temporaries that turn out to be unnecessary, so + there is little reason for the setf-method itself to optimize. + + -- Function: get-setf-method place &optional env + This function returns the setf-method for PLACE, by invoking the + definition previously recorded by `defsetf' or + `define-setf-method'. The result is a list of five values as + described above. You can use this function to build your own + `incf'-like modify macros. (Actually, it is better to use the + internal functions `cl-setf-do-modify' and `cl-setf-do-store', + which are a bit easier to use and which also do a number of + optimizations; consult the source code for the `incf' function for + a simple example.) + + The argument ENV specifies the "environment" to be passed on to + `macroexpand' if `get-setf-method' should need to expand a macro + in PLACE. It should come from an `&environment' argument to the + macro or setf-method that called `get-setf-method'. + + See also the source code for the setf-methods for `apply' and + `substring', each of which works by calling `get-setf-method' on a + simpler case, then massaging the result in various ways. + + Modern Common Lisp defines a second, independent way to specify the +`setf' behavior of a function, namely "`setf' functions" whose names +are lists `(setf NAME)' rather than symbols. For example, `(defun +(setf foo) ...)' defines the function that is used when `setf' is +applied to `foo'. This package does not currently support `setf' +functions. In particular, it is a compile-time error to use `setf' on +a form which has not already been `defsetf''d or otherwise declared; in +newer Common Lisps, this would not be an error since the function +`(setf FUNC)' might be defined later. + + +File: cl.info, Node: Variable Bindings, Next: Conditionals, Prev: Generalized Variables, Up: Control Structure + +5.3 Variable Bindings +===================== + +These Lisp forms make bindings to variables and function names, +analogous to Lisp's built-in `let' form. + + *Note Modify Macros::, for the `letf' and `letf*' forms which are +also related to variable bindings. + +* Menu: + +* Dynamic Bindings:: The `progv' form +* Lexical Bindings:: `lexical-let' and lexical closures +* Function Bindings:: `flet' and `labels' +* Macro Bindings:: `macrolet' and `symbol-macrolet' + + +File: cl.info, Node: Dynamic Bindings, Next: Lexical Bindings, Prev: Variable Bindings, Up: Variable Bindings + +5.3.1 Dynamic Bindings +---------------------- + +The standard `let' form binds variables whose names are known at +compile-time. The `progv' form provides an easy way to bind variables +whose names are computed at run-time. + + -- Special Form: progv symbols values forms... + This form establishes `let'-style variable bindings on a set of + variables computed at run-time. The expressions SYMBOLS and + VALUES are evaluated, and must return lists of symbols and values, + respectively. The symbols are bound to the corresponding values + for the duration of the body FORMs. If VALUES is shorter than + SYMBOLS, the last few symbols are made unbound (as if by + `makunbound') inside the body. If SYMBOLS is shorter than VALUES, + the excess values are ignored. + + +File: cl.info, Node: Lexical Bindings, Next: Function Bindings, Prev: Dynamic Bindings, Up: Variable Bindings + +5.3.2 Lexical Bindings +---------------------- + +The "CL" package defines the following macro which more closely follows +the Common Lisp `let' form: + + -- Special Form: lexical-let (bindings...) forms... + This form is exactly like `let' except that the bindings it + establishes are purely lexical. Lexical bindings are similar to + local variables in a language like C: Only the code physically + within the body of the `lexical-let' (after macro expansion) may + refer to the bound variables. + + (setq a 5) + (defun foo (b) (+ a b)) + (let ((a 2)) (foo a)) + => 4 + (lexical-let ((a 2)) (foo a)) + => 7 + + In this example, a regular `let' binding of `a' actually makes a + temporary change to the global variable `a', so `foo' is able to + see the binding of `a' to 2. But `lexical-let' actually creates a + distinct local variable `a' for use within its body, without any + effect on the global variable of the same name. + + The most important use of lexical bindings is to create "closures". + A closure is a function object that refers to an outside lexical + variable. For example: + + (defun make-adder (n) + (lexical-let ((n n)) + (function (lambda (m) (+ n m))))) + (setq add17 (make-adder 17)) + (funcall add17 4) + => 21 + + The call `(make-adder 17)' returns a function object which adds 17 + to its argument. If `let' had been used instead of `lexical-let', + the function object would have referred to the global `n', which + would have been bound to 17 only during the call to `make-adder' + itself. + + (defun make-counter () + (lexical-let ((n 0)) + (function* (lambda (&optional (m 1)) (incf n m))))) + (setq count-1 (make-counter)) + (funcall count-1 3) + => 3 + (funcall count-1 14) + => 17 + (setq count-2 (make-counter)) + (funcall count-2 5) + => 5 + (funcall count-1 2) + => 19 + (funcall count-2) + => 6 + + Here we see that each call to `make-counter' creates a distinct + local variable `n', which serves as a private counter for the + function object that is returned. + + Closed-over lexical variables persist until the last reference to + them goes away, just like all other Lisp objects. For example, + `count-2' refers to a function object which refers to an instance + of the variable `n'; this is the only reference to that variable, + so after `(setq count-2 nil)' the garbage collector would be able + to delete this instance of `n'. Of course, if a `lexical-let' + does not actually create any closures, then the lexical variables + are free as soon as the `lexical-let' returns. + + Many closures are used only during the extent of the bindings they + refer to; these are known as "downward funargs" in Lisp parlance. + When a closure is used in this way, regular Emacs Lisp dynamic + bindings suffice and will be more efficient than `lexical-let' + closures: + + (defun add-to-list (x list) + (mapcar (function (lambda (y) (+ x y))) list)) + (add-to-list 7 '(1 2 5)) + => (8 9 12) + + Since this lambda is only used while `x' is still bound, it is not + necessary to make a true closure out of it. + + You can use `defun' or `flet' inside a `lexical-let' to create a + named closure. If several closures are created in the body of a + single `lexical-let', they all close over the same instance of the + lexical variable. + + The `lexical-let' form is an extension to Common Lisp. In true + Common Lisp, all bindings are lexical unless declared otherwise. + + -- Special Form: lexical-let* (bindings...) forms... + This form is just like `lexical-let', except that the bindings are + made sequentially in the manner of `let*'. + + +File: cl.info, Node: Function Bindings, Next: Macro Bindings, Prev: Lexical Bindings, Up: Variable Bindings + +5.3.3 Function Bindings +----------------------- + +These forms make `let'-like bindings to functions instead of variables. + + -- Special Form: flet (bindings...) forms... + This form establishes `let'-style bindings on the function cells + of symbols rather than on the value cells. Each BINDING must be a + list of the form `(NAME ARGLIST FORMS...)', which defines a + function exactly as if it were a `defun*' form. The function NAME + is defined accordingly for the duration of the body of the `flet'; + then the old function definition, or lack thereof, is restored. + + While `flet' in Common Lisp establishes a lexical binding of NAME, + Emacs Lisp `flet' makes a dynamic binding. The result is that + `flet' affects indirect calls to a function as well as calls + directly inside the `flet' form itself. + + You can use `flet' to disable or modify the behavior of a function + in a temporary fashion. This will even work on Emacs primitives, + although note that some calls to primitive functions internal to + Emacs are made without going through the symbol's function cell, + and so will not be affected by `flet'. For example, + + (flet ((message (&rest args) (push args saved-msgs))) + (do-something)) + + This code attempts to replace the built-in function `message' with + a function that simply saves the messages in a list rather than + displaying them. The original definition of `message' will be + restored after `do-something' exits. This code will work fine on + messages generated by other Lisp code, but messages generated + directly inside Emacs will not be caught since they make direct + C-language calls to the message routines rather than going through + the Lisp `message' function. + + Functions defined by `flet' may use the full Common Lisp argument + notation supported by `defun*'; also, the function body is + enclosed in an implicit block as if by `defun*'. *Note Program + Structure::. + + -- Special Form: labels (bindings...) forms... + The `labels' form is a synonym for `flet'. (In Common Lisp, + `labels' and `flet' differ in ways that depend on their lexical + scoping; these distinctions vanish in dynamically scoped Emacs + Lisp.) + + +File: cl.info, Node: Macro Bindings, Prev: Function Bindings, Up: Variable Bindings + +5.3.4 Macro Bindings +-------------------- + +These forms create local macros and "symbol macros." + + -- Special Form: macrolet (bindings...) forms... + This form is analogous to `flet', but for macros instead of + functions. Each BINDING is a list of the same form as the + arguments to `defmacro*' (i.e., a macro name, argument list, and + macro-expander forms). The macro is defined accordingly for use + within the body of the `macrolet'. + + Because of the nature of macros, `macrolet' is lexically scoped + even in Emacs Lisp: The `macrolet' binding will affect only calls + that appear physically within the body FORMS, possibly after + expansion of other macros in the body. + + -- Special Form: symbol-macrolet (bindings...) forms... + This form creates "symbol macros", which are macros that look like + variable references rather than function calls. Each BINDING is a + list `(VAR EXPANSION)'; any reference to VAR within the body FORMS + is replaced by EXPANSION. + + (setq bar '(5 . 9)) + (symbol-macrolet ((foo (car bar))) + (incf foo)) + bar + => (6 . 9) + + A `setq' of a symbol macro is treated the same as a `setf'. I.e., + `(setq foo 4)' in the above would be equivalent to `(setf foo 4)', + which in turn expands to `(setf (car bar) 4)'. + + Likewise, a `let' or `let*' binding a symbol macro is treated like + a `letf' or `letf*'. This differs from true Common Lisp, where + the rules of lexical scoping cause a `let' binding to shadow a + `symbol-macrolet' binding. In this package, only `lexical-let' + and `lexical-let*' will shadow a symbol macro. + + There is no analogue of `defmacro' for symbol macros; all symbol + macros are local. A typical use of `symbol-macrolet' is in the + expansion of another macro: + + (defmacro* my-dolist ((x list) &rest body) + (let ((var (gensym))) + (list 'loop 'for var 'on list 'do + (list* 'symbol-macrolet (list (list x (list 'car var))) + body)))) + + (setq mylist '(1 2 3 4)) + (my-dolist (x mylist) (incf x)) + mylist + => (2 3 4 5) + + In this example, the `my-dolist' macro is similar to `dolist' + (*note Iteration::) except that the variable `x' becomes a true + reference onto the elements of the list. The `my-dolist' call + shown here expands to + + (loop for G1234 on mylist do + (symbol-macrolet ((x (car G1234))) + (incf x))) + + which in turn expands to + + (loop for G1234 on mylist do (incf (car G1234))) + + *Note Loop Facility::, for a description of the `loop' macro. + This package defines a nonstandard `in-ref' loop clause that works + much like `my-dolist'. + + +File: cl.info, Node: Conditionals, Next: Blocks and Exits, Prev: Variable Bindings, Up: Control Structure + +5.4 Conditionals +================ + +These conditional forms augment Emacs Lisp's simple `if', `and', `or', +and `cond' forms. + + -- Special Form: when test forms... + This is a variant of `if' where there are no "else" forms, and + possibly several "then" forms. In particular, + + (when TEST A B C) + + is entirely equivalent to + + (if TEST (progn A B C) nil) + + -- Special Form: unless test forms... + This is a variant of `if' where there are no "then" forms, and + possibly several "else" forms: + + (unless TEST A B C) + + is entirely equivalent to + + (when (not TEST) A B C) + + -- Special Form: case keyform clause... + This macro evaluates KEYFORM, then compares it with the key values + listed in the various CLAUSEs. Whichever clause matches the key + is executed; comparison is done by `eql'. If no clause matches, + the `case' form returns `nil'. The clauses are of the form + + (KEYLIST BODY-FORMS...) + + where KEYLIST is a list of key values. If there is exactly one + value, and it is not a cons cell or the symbol `nil' or `t', then + it can be used by itself as a KEYLIST without being enclosed in a + list. All key values in the `case' form must be distinct. The + final clauses may use `t' in place of a KEYLIST to indicate a + default clause that should be taken if none of the other clauses + match. (The symbol `otherwise' is also recognized in place of + `t'. To make a clause that matches the actual symbol `t', `nil', + or `otherwise', enclose the symbol in a list.) + + For example, this expression reads a keystroke, then does one of + four things depending on whether it is an `a', a `b', a or + , or anything else. + + (case (read-char) + (?a (do-a-thing)) + (?b (do-b-thing)) + ((?\r ?\n) (do-ret-thing)) + (t (do-other-thing))) + + -- Special Form: ecase keyform clause... + This macro is just like `case', except that if the key does not + match any of the clauses, an error is signalled rather than simply + returning `nil'. + + -- Special Form: typecase keyform clause... + This macro is a version of `case' that checks for types rather + than values. Each CLAUSE is of the form `(TYPE BODY...)'. *Note + Type Predicates::, for a description of type specifiers. For + example, + + (typecase x + (integer (munch-integer x)) + (float (munch-float x)) + (string (munch-integer (string-to-int x))) + (t (munch-anything x))) + + The type specifier `t' matches any type of object; the word + `otherwise' is also allowed. To make one clause match any of + several types, use an `(or ...)' type specifier. + + -- Special Form: etypecase keyform clause... + This macro is just like `typecase', except that if the key does + not match any of the clauses, an error is signalled rather than + simply returning `nil'. + + +File: cl.info, Node: Blocks and Exits, Next: Iteration, Prev: Conditionals, Up: Control Structure + +5.5 Blocks and Exits +==================== + +Common Lisp "blocks" provide a non-local exit mechanism very similar to +`catch' and `throw', but lexically rather than dynamically scoped. +This package actually implements `block' in terms of `catch'; however, +the lexical scoping allows the optimizing byte-compiler to omit the +costly `catch' step if the body of the block does not actually +`return-from' the block. + + -- Special Form: block name forms... + The FORMS are evaluated as if by a `progn'. However, if any of + the FORMS execute `(return-from NAME)', they will jump out and + return directly from the `block' form. The `block' returns the + result of the last FORM unless a `return-from' occurs. + + The `block'/`return-from' mechanism is quite similar to the + `catch'/`throw' mechanism. The main differences are that block + NAMEs are unevaluated symbols, rather than forms (such as quoted + symbols) which evaluate to a tag at run-time; and also that blocks + are lexically scoped whereas `catch'/`throw' are dynamically + scoped. This means that functions called from the body of a + `catch' can also `throw' to the `catch', but the `return-from' + referring to a block name must appear physically within the FORMS + that make up the body of the block. They may not appear within + other called functions, although they may appear within macro + expansions or `lambda's in the body. Block names and `catch' + names form independent name-spaces. + + In true Common Lisp, `defun' and `defmacro' surround the function + or expander bodies with implicit blocks with the same name as the + function or macro. This does not occur in Emacs Lisp, but this + package provides `defun*' and `defmacro*' forms which do create + the implicit block. + + The Common Lisp looping constructs defined by this package, such + as `loop' and `dolist', also create implicit blocks just as in + Common Lisp. + + Because they are implemented in terms of Emacs Lisp `catch' and + `throw', blocks have the same overhead as actual `catch' + constructs (roughly two function calls). However, Zawinski and + Furuseth's optimizing byte compiler (standard in Emacs 19) will + optimize away the `catch' if the block does not in fact contain + any `return' or `return-from' calls that jump to it. This means + that `do' loops and `defun*' functions which don't use `return' + don't pay the overhead to support it. + + -- Special Form: return-from name [result] + This macro returns from the block named NAME, which must be an + (unevaluated) symbol. If a RESULT form is specified, it is + evaluated to produce the result returned from the `block'. + Otherwise, `nil' is returned. + + -- Special Form: return [result] + This macro is exactly like `(return-from nil RESULT)'. Common + Lisp loops like `do' and `dolist' implicitly enclose themselves in + `nil' blocks. + + +File: cl.info, Node: Iteration, Next: Loop Facility, Prev: Blocks and Exits, Up: Control Structure + +5.6 Iteration +============= + +The macros described here provide more sophisticated, high-level +looping constructs to complement Emacs Lisp's basic `while' loop. + + -- Special Form: loop forms... + The "CL" package supports both the simple, old-style meaning of + `loop' and the extremely powerful and flexible feature known as + the "Loop Facility" or "Loop Macro". This more advanced facility + is discussed in the following section; *note Loop Facility::. The + simple form of `loop' is described here. + + If `loop' is followed by zero or more Lisp expressions, then + `(loop EXPRS...)' simply creates an infinite loop executing the + expressions over and over. The loop is enclosed in an implicit + `nil' block. Thus, + + (loop (foo) (if (no-more) (return 72)) (bar)) + + is exactly equivalent to + + (block nil (while t (foo) (if (no-more) (return 72)) (bar))) + + If any of the expressions are plain symbols, the loop is instead + interpreted as a Loop Macro specification as described later. + (This is not a restriction in practice, since a plain symbol in + the above notation would simply access and throw away the value of + a variable.) + + -- Special Form: do (spec...) (end-test [result...]) forms... + This macro creates a general iterative loop. Each SPEC is of the + form + + (VAR [INIT [STEP]]) + + The loop works as follows: First, each VAR is bound to the + associated INIT value as if by a `let' form. Then, in each + iteration of the loop, the END-TEST is evaluated; if true, the + loop is finished. Otherwise, the body FORMS are evaluated, then + each VAR is set to the associated STEP expression (as if by a + `psetq' form) and the next iteration begins. Once the END-TEST + becomes true, the RESULT forms are evaluated (with the VARs still + bound to their values) to produce the result returned by `do'. + + The entire `do' loop is enclosed in an implicit `nil' block, so + that you can use `(return)' to break out of the loop at any time. + + If there are no RESULT forms, the loop returns `nil'. If a given + VAR has no STEP form, it is bound to its INIT value but not + otherwise modified during the `do' loop (unless the code + explicitly modifies it); this case is just a shorthand for putting + a `(let ((VAR INIT)) ...)' around the loop. If INIT is also + omitted it defaults to `nil', and in this case a plain `VAR' can + be used in place of `(VAR)', again following the analogy with + `let'. + + This example (from Steele) illustrates a loop which applies the + function `f' to successive pairs of values from the lists `foo' + and `bar'; it is equivalent to the call `(mapcar* 'f foo bar)'. + Note that this loop has no body FORMS at all, performing all its + work as side effects of the rest of the loop. + + (do ((x foo (cdr x)) + (y bar (cdr y)) + (z nil (cons (f (car x) (car y)) z))) + ((or (null x) (null y)) + (nreverse z))) + + -- Special Form: do* (spec...) (end-test [result...]) forms... + This is to `do' what `let*' is to `let'. In particular, the + initial values are bound as if by `let*' rather than `let', and + the steps are assigned as if by `setq' rather than `psetq'. + + Here is another way to write the above loop: + + (do* ((xp foo (cdr xp)) + (yp bar (cdr yp)) + (x (car xp) (car xp)) + (y (car yp) (car yp)) + z) + ((or (null xp) (null yp)) + (nreverse z)) + (push (f x y) z)) + + -- Special Form: dolist (var list [result]) forms... + This is a more specialized loop which iterates across the elements + of a list. LIST should evaluate to a list; the body FORMS are + executed with VAR bound to each element of the list in turn. + Finally, the RESULT form (or `nil') is evaluated with VAR bound to + `nil' to produce the result returned by the loop. The loop is + surrounded by an implicit `nil' block. + + -- Special Form: dotimes (var count [result]) forms... + This is a more specialized loop which iterates a specified number + of times. The body is executed with VAR bound to the integers + from zero (inclusive) to COUNT (exclusive), in turn. Then the + `result' form is evaluated with VAR bound to the total number of + iterations that were done (i.e., `(max 0 COUNT)') to get the + return value for the loop form. The loop is surrounded by an + implicit `nil' block. + + -- Special Form: do-symbols (var [obarray [result]]) forms... + This loop iterates over all interned symbols. If OBARRAY is + specified and is not `nil', it loops over all symbols in that + obarray. For each symbol, the body FORMS are evaluated with VAR + bound to that symbol. The symbols are visited in an unspecified + order. Afterward the RESULT form, if any, is evaluated (with VAR + bound to `nil') to get the return value. The loop is surrounded + by an implicit `nil' block. + + -- Special Form: do-all-symbols (var [result]) forms... + This is identical to `do-symbols' except that the OBARRAY argument + is omitted; it always iterates over the default obarray. + + *Note Mapping over Sequences::, for some more functions for +iterating over vectors or lists. + + +File: cl.info, Node: Loop Facility, Next: Multiple Values, Prev: Iteration, Up: Control Structure + +5.7 Loop Facility +================= + +A common complaint with Lisp's traditional looping constructs is that +they are either too simple and limited, such as Common Lisp's `dotimes' +or Emacs Lisp's `while', or too unreadable and obscure, like Common +Lisp's `do' loop. + + To remedy this, recent versions of Common Lisp have added a new +construct called the "Loop Facility" or "`loop' macro," with an +easy-to-use but very powerful and expressive syntax. + +* Menu: + +* Loop Basics:: `loop' macro, basic clause structure +* Loop Examples:: Working examples of `loop' macro +* For Clauses:: Clauses introduced by `for' or `as' +* Iteration Clauses:: `repeat', `while', `thereis', etc. +* Accumulation Clauses:: `collect', `sum', `maximize', etc. +* Other Clauses:: `with', `if', `initially', `finally' + + +File: cl.info, Node: Loop Basics, Next: Loop Examples, Prev: Loop Facility, Up: Loop Facility + +5.7.1 Loop Basics +----------------- + +The `loop' macro essentially creates a mini-language within Lisp that +is specially tailored for describing loops. While this language is a +little strange-looking by the standards of regular Lisp, it turns out +to be very easy to learn and well-suited to its purpose. + + Since `loop' is a macro, all parsing of the loop language takes +place at byte-compile time; compiled `loop's are just as efficient as +the equivalent `while' loops written longhand. + + -- Special Form: loop clauses... + A loop construct consists of a series of CLAUSEs, each introduced + by a symbol like `for' or `do'. Clauses are simply strung + together in the argument list of `loop', with minimal extra + parentheses. The various types of clauses specify + initializations, such as the binding of temporary variables, + actions to be taken in the loop, stepping actions, and final + cleanup. + + Common Lisp specifies a certain general order of clauses in a loop: + + (loop NAME-CLAUSE + VAR-CLAUSES... + ACTION-CLAUSES...) + + The NAME-CLAUSE optionally gives a name to the implicit block that + surrounds the loop. By default, the implicit block is named + `nil'. The VAR-CLAUSES specify what variables should be bound + during the loop, and how they should be modified or iterated + throughout the course of the loop. The ACTION-CLAUSES are things + to be done during the loop, such as computing, collecting, and + returning values. + + The Emacs version of the `loop' macro is less restrictive about + the order of clauses, but things will behave most predictably if + you put the variable-binding clauses `with', `for', and `repeat' + before the action clauses. As in Common Lisp, `initially' and + `finally' clauses can go anywhere. + + Loops generally return `nil' by default, but you can cause them to + return a value by using an accumulation clause like `collect', an + end-test clause like `always', or an explicit `return' clause to + jump out of the implicit block. (Because the loop body is + enclosed in an implicit block, you can also use regular Lisp + `return' or `return-from' to break out of the loop.) + + The following sections give some examples of the Loop Macro in +action, and describe the particular loop clauses in great detail. +Consult the second edition of Steele's "Common Lisp, the Language", for +additional discussion and examples of the `loop' macro. + + +File: cl.info, Node: Loop Examples, Next: For Clauses, Prev: Loop Basics, Up: Loop Facility + +5.7.2 Loop Examples +------------------- + +Before listing the full set of clauses that are allowed, let's look at +a few example loops just to get a feel for the `loop' language. + + (loop for buf in (buffer-list) + collect (buffer-file-name buf)) + +This loop iterates over all Emacs buffers, using the list returned by +`buffer-list'. For each buffer `buf', it calls `buffer-file-name' and +collects the results into a list, which is then returned from the +`loop' construct. The result is a list of the file names of all the +buffers in Emacs' memory. The words `for', `in', and `collect' are +reserved words in the `loop' language. + + (loop repeat 20 do (insert "Yowsa\n")) + +This loop inserts the phrase "Yowsa" twenty times in the current buffer. + + (loop until (eobp) do (munch-line) (forward-line 1)) + +This loop calls `munch-line' on every line until the end of the buffer. +If point is already at the end of the buffer, the loop exits +immediately. + + (loop do (munch-line) until (eobp) do (forward-line 1)) + +This loop is similar to the above one, except that `munch-line' is +always called at least once. + + (loop for x from 1 to 100 + for y = (* x x) + until (>= y 729) + finally return (list x (= y 729))) + +This more complicated loop searches for a number `x' whose square is +729. For safety's sake it only examines `x' values up to 100; dropping +the phrase `to 100' would cause the loop to count upwards with no +limit. The second `for' clause defines `y' to be the square of `x' +within the loop; the expression after the `=' sign is reevaluated each +time through the loop. The `until' clause gives a condition for +terminating the loop, and the `finally' clause says what to do when the +loop finishes. (This particular example was written less concisely +than it could have been, just for the sake of illustration.) + + Note that even though this loop contains three clauses (two `for's +and an `until') that would have been enough to define loops all by +themselves, it still creates a single loop rather than some sort of +triple-nested loop. You must explicitly nest your `loop' constructs if +you want nested loops. + + +File: cl.info, Node: For Clauses, Next: Iteration Clauses, Prev: Loop Examples, Up: Loop Facility + +5.7.3 For Clauses +----------------- + +Most loops are governed by one or more `for' clauses. A `for' clause +simultaneously describes variables to be bound, how those variables are +to be stepped during the loop, and usually an end condition based on +those variables. + + The word `as' is a synonym for the word `for'. This word is +followed by a variable name, then a word like `from' or `across' that +describes the kind of iteration desired. In Common Lisp, the phrase +`being the' sometimes precedes the type of iteration; in this package +both `being' and `the' are optional. The word `each' is a synonym for +`the', and the word that follows it may be singular or plural: `for x +being the elements of y' or `for x being each element of y'. Which +form you use is purely a matter of style. + + The variable is bound around the loop as if by `let': + + (setq i 'happy) + (loop for i from 1 to 10 do (do-something-with i)) + i + => happy + +`for VAR from EXPR1 to EXPR2 by EXPR3' + This type of `for' clause creates a counting loop. Each of the + three sub-terms is optional, though there must be at least one + term so that the clause is marked as a counting clause. + + The three expressions are the starting value, the ending value, and + the step value, respectively, of the variable. The loop counts + upwards by default (EXPR3 must be positive), from EXPR1 to EXPR2 + inclusively. If you omit the `from' term, the loop counts from + zero; if you omit the `to' term, the loop counts forever without + stopping (unless stopped by some other loop clause, of course); if + you omit the `by' term, the loop counts in steps of one. + + You can replace the word `from' with `upfrom' or `downfrom' to + indicate the direction of the loop. Likewise, you can replace + `to' with `upto' or `downto'. For example, `for x from 5 downto + 1' executes five times with `x' taking on the integers from 5 down + to 1 in turn. Also, you can replace `to' with `below' or `above', + which are like `upto' and `downto' respectively except that they + are exclusive rather than inclusive limits: + + (loop for x to 10 collect x) + => (0 1 2 3 4 5 6 7 8 9 10) + (loop for x below 10 collect x) + => (0 1 2 3 4 5 6 7 8 9) + + The `by' value is always positive, even for downward-counting + loops. Some sort of `from' value is required for downward loops; + `for x downto 5' is not a legal loop clause all by itself. + +`for VAR in LIST by FUNCTION' + This clause iterates VAR over all the elements of LIST, in turn. + If you specify the `by' term, then FUNCTION is used to traverse + the list instead of `cdr'; it must be a function taking one + argument. For example: + + (loop for x in '(1 2 3 4 5 6) collect (* x x)) + => (1 4 9 16 25 36) + (loop for x in '(1 2 3 4 5 6) by 'cddr collect (* x x)) + => (1 9 25) + +`for VAR on LIST by FUNCTION' + This clause iterates VAR over all the cons cells of LIST. + + (loop for x on '(1 2 3 4) collect x) + => ((1 2 3 4) (2 3 4) (3 4) (4)) + + With `by', there is no real reason that the `on' expression must + be a list. For example: + + (loop for x on first-animal by 'next-animal collect x) + + where `(next-animal x)' takes an "animal" X and returns the next + in the (assumed) sequence of animals, or `nil' if X was the last + animal in the sequence. + +`for VAR in-ref LIST by FUNCTION' + This is like a regular `in' clause, but VAR becomes a `setf'-able + "reference" onto the elements of the list rather than just a + temporary variable. For example, + + (loop for x in-ref my-list do (incf x)) + + increments every element of `my-list' in place. This clause is an + extension to standard Common Lisp. + +`for VAR across ARRAY' + This clause iterates VAR over all the elements of ARRAY, which may + be a vector or a string. + + (loop for x across "aeiou" + do (use-vowel (char-to-string x))) + +`for VAR across-ref ARRAY' + This clause iterates over an array, with VAR a `setf'-able + reference onto the elements; see `in-ref' above. + +`for VAR being the elements of SEQUENCE' + This clause iterates over the elements of SEQUENCE, which may be a + list, vector, or string. Since the type must be determined at + run-time, this is somewhat less efficient than `in' or `across'. + The clause may be followed by the additional term `using (index + VAR2)' to cause VAR2 to be bound to the successive indices + (starting at 0) of the elements. + + This clause type is taken from older versions of the `loop' macro, + and is not present in modern Common Lisp. The `using (sequence + ...)' term of the older macros is not supported. + +`for VAR being the elements of-ref SEQUENCE' + This clause iterates over a sequence, with VAR a `setf'-able + reference onto the elements; see `in-ref' above. + +`for VAR being the symbols [of OBARRAY]' + This clause iterates over symbols, either over all interned symbols + or over all symbols in OBARRAY. The loop is executed with VAR + bound to each symbol in turn. The symbols are visited in an + unspecified order. + + As an example, + + (loop for sym being the symbols + when (fboundp sym) + when (string-match "^map" (symbol-name sym)) + collect sym) + + returns a list of all the functions whose names begin with `map'. + + The Common Lisp words `external-symbols' and `present-symbols' are + also recognized but are equivalent to `symbols' in Emacs Lisp. + + Due to a minor implementation restriction, it will not work to have + more than one `for' clause iterating over symbols, hash tables, + keymaps, overlays, or intervals in a given `loop'. Fortunately, + it would rarely if ever be useful to do so. It _is_ legal to mix + one of these types of clauses with other clauses like `for ... to' + or `while'. + +`for VAR being the hash-keys of HASH-TABLE' + This clause iterates over the entries in HASH-TABLE. For each + hash table entry, VAR is bound to the entry's key. If you write + `the hash-values' instead, VAR is bound to the values of the + entries. The clause may be followed by the additional term `using + (hash-values VAR2)' (where `hash-values' is the opposite word of + the word following `the') to cause VAR and VAR2 to be bound to the + two parts of each hash table entry. + +`for VAR being the key-codes of KEYMAP' + This clause iterates over the entries in KEYMAP. In GNU Emacs 18 + and 19, keymaps are either alists or vectors, and key-codes are + integers or symbols. In XEmacs, keymaps are a special new data + type, and key-codes are symbols or lists of symbols. The + iteration does not enter nested keymaps or inherited (parent) + keymaps. You can use `the key-bindings' to access the commands + bound to the keys rather than the key codes, and you can add a + `using' clause to access both the codes and the bindings together. + +`for VAR being the key-seqs of KEYMAP' + This clause iterates over all key sequences defined by KEYMAP and + its nested keymaps, where VAR takes on values which are strings in + Emacs 18 or vectors in Emacs 19. The strings or vectors are + reused for each iteration, so you must copy them if you wish to + keep them permanently. You can add a `using (key-bindings ...)' + clause to get the command bindings as well. + +`for VAR being the overlays [of BUFFER] ...' + This clause iterates over the Emacs 19 "overlays" or XEmacs + "extents" of a buffer (the clause `extents' is synonymous with + `overlays'). Under Emacs 18, this clause iterates zero times. If + the `of' term is omitted, the current buffer is used. This clause + also accepts optional `from POS' and `to POS' terms, limiting the + clause to overlays which overlap the specified region. + +`for VAR being the intervals [of BUFFER] ...' + This clause iterates over all intervals of a buffer with constant + text properties. The variable VAR will be bound to conses of + start and end positions, where one start position is always equal + to the previous end position. The clause allows `of', `from', + `to', and `property' terms, where the latter term restricts the + search to just the specified property. The `of' term may specify + either a buffer or a string. This clause is useful only in GNU + Emacs 19; in other versions, all buffers and strings consist of a + single interval. + +`for VAR being the frames' + This clause iterates over all frames, i.e., X window system windows + open on Emacs files. This clause works only under Emacs 19. The + clause `screens' is a synonym for `frames'. The frames are + visited in `next-frame' order starting from `selected-frame'. + +`for VAR being the windows [of FRAME]' + This clause iterates over the windows (in the Emacs sense) of the + current frame, or of the specified FRAME. (In Emacs 18 there is + only ever one frame, and the `of' term is not allowed there.) + +`for VAR being the buffers' + This clause iterates over all buffers in Emacs. It is equivalent + to `for VAR in (buffer-list)'. + +`for VAR = EXPR1 then EXPR2' + This clause does a general iteration. The first time through the + loop, VAR will be bound to EXPR1. On the second and successive + iterations it will be set by evaluating EXPR2 (which may refer to + the old value of VAR). For example, these two loops are + effectively the same: + + (loop for x on my-list by 'cddr do ...) + (loop for x = my-list then (cddr x) while x do ...) + + Note that this type of `for' clause does not imply any sort of + terminating condition; the above example combines it with a + `while' clause to tell when to end the loop. + + If you omit the `then' term, EXPR1 is used both for the initial + setting and for successive settings: + + (loop for x = (random) when (> x 0) return x) + + This loop keeps taking random numbers from the `(random)' function + until it gets a positive one, which it then returns. + + If you include several `for' clauses in a row, they are treated +sequentially (as if by `let*' and `setq'). You can instead use the +word `and' to link the clauses, in which case they are processed in +parallel (as if by `let' and `psetq'). + + (loop for x below 5 for y = nil then x collect (list x y)) + => ((0 nil) (1 1) (2 2) (3 3) (4 4)) + (loop for x below 5 and y = nil then x collect (list x y)) + => ((0 nil) (1 0) (2 1) (3 2) (4 3)) + +In the first loop, `y' is set based on the value of `x' that was just +set by the previous clause; in the second loop, `x' and `y' are set +simultaneously so `y' is set based on the value of `x' left over from +the previous time through the loop. + + Another feature of the `loop' macro is "destructuring", similar in +concept to the destructuring provided by `defmacro'. The VAR part of +any `for' clause can be given as a list of variables instead of a +single variable. The values produced during loop execution must be +lists; the values in the lists are stored in the corresponding +variables. + + (loop for (x y) in '((2 3) (4 5) (6 7)) collect (+ x y)) + => (5 9 13) + + In loop destructuring, if there are more values than variables the +trailing values are ignored, and if there are more variables than +values the trailing variables get the value `nil'. If `nil' is used as +a variable name, the corresponding values are ignored. Destructuring +may be nested, and dotted lists of variables like `(x . y)' are allowed. + + +File: cl.info, Node: Iteration Clauses, Next: Accumulation Clauses, Prev: For Clauses, Up: Loop Facility + +5.7.4 Iteration Clauses +----------------------- + +Aside from `for' clauses, there are several other loop clauses that +control the way the loop operates. They might be used by themselves, +or in conjunction with one or more `for' clauses. + +`repeat INTEGER' + This clause simply counts up to the specified number using an + internal temporary variable. The loops + + (loop repeat n do ...) + (loop for temp to n do ...) + + are identical except that the second one forces you to choose a + name for a variable you aren't actually going to use. + +`while CONDITION' + This clause stops the loop when the specified condition (any Lisp + expression) becomes `nil'. For example, the following two loops + are equivalent, except for the implicit `nil' block that surrounds + the second one: + + (while COND FORMS...) + (loop while COND do FORMS...) + +`until CONDITION' + This clause stops the loop when the specified condition is true, + i.e., non-`nil'. + +`always CONDITION' + This clause stops the loop when the specified condition is `nil'. + Unlike `while', it stops the loop using `return nil' so that the + `finally' clauses are not executed. If all the conditions were + non-`nil', the loop returns `t': + + (if (loop for size in size-list always (> size 10)) + (some-big-sizes) + (no-big-sizes)) + +`never CONDITION' + This clause is like `always', except that the loop returns `t' if + any conditions were false, or `nil' otherwise. + +`thereis CONDITION' + This clause stops the loop when the specified form is non-`nil'; + in this case, it returns that non-`nil' value. If all the values + were `nil', the loop returns `nil'. + + +File: cl.info, Node: Accumulation Clauses, Next: Other Clauses, Prev: Iteration Clauses, Up: Loop Facility + +5.7.5 Accumulation Clauses +-------------------------- + +These clauses cause the loop to accumulate information about the +specified Lisp FORM. The accumulated result is returned from the loop +unless overridden, say, by a `return' clause. + +`collect FORM' + This clause collects the values of FORM into a list. Several + examples of `collect' appear elsewhere in this manual. + + The word `collecting' is a synonym for `collect', and likewise for + the other accumulation clauses. + +`append FORM' + This clause collects lists of values into a result list using + `append'. + +`nconc FORM' + This clause collects lists of values into a result list by + destructively modifying the lists rather than copying them. + +`concat FORM' + This clause concatenates the values of the specified FORM into a + string. (It and the following clause are extensions to standard + Common Lisp.) + +`vconcat FORM' + This clause concatenates the values of the specified FORM into a + vector. + +`count FORM' + This clause counts the number of times the specified FORM + evaluates to a non-`nil' value. + +`sum FORM' + This clause accumulates the sum of the values of the specified + FORM, which must evaluate to a number. + +`maximize FORM' + This clause accumulates the maximum value of the specified FORM, + which must evaluate to a number. The return value is undefined if + `maximize' is executed zero times. + +`minimize FORM' + This clause accumulates the minimum value of the specified FORM. + + Accumulation clauses can be followed by `into VAR' to cause the data +to be collected into variable VAR (which is automatically `let'-bound +during the loop) rather than an unnamed temporary variable. Also, +`into' accumulations do not automatically imply a return value. The +loop must use some explicit mechanism, such as `finally return', to +return the accumulated result. + + It is legal for several accumulation clauses of the same type to +accumulate into the same place. From Steele: + + (loop for name in '(fred sue alice joe june) + for kids in '((bob ken) () () (kris sunshine) ()) + collect name + append kids) + => (fred bob ken sue alice joe kris sunshine june) + + +File: cl.info, Node: Other Clauses, Prev: Accumulation Clauses, Up: Loop Facility + +5.7.6 Other Clauses +------------------- + +This section describes the remaining loop clauses. + +`with VAR = VALUE' + This clause binds a variable to a value around the loop, but + otherwise leaves the variable alone during the loop. The following + loops are basically equivalent: + + (loop with x = 17 do ...) + (let ((x 17)) (loop do ...)) + (loop for x = 17 then x do ...) + + Naturally, the variable VAR might be used for some purpose in the + rest of the loop. For example: + + (loop for x in my-list with res = nil do (push x res) + finally return res) + + This loop inserts the elements of `my-list' at the front of a new + list being accumulated in `res', then returns the list `res' at + the end of the loop. The effect is similar to that of a `collect' + clause, but the list gets reversed by virtue of the fact that + elements are being pushed onto the front of `res' rather than the + end. + + If you omit the `=' term, the variable is initialized to `nil'. + (Thus the `= nil' in the above example is unnecessary.) + + Bindings made by `with' are sequential by default, as if by + `let*'. Just like `for' clauses, `with' clauses can be linked + with `and' to cause the bindings to be made by `let' instead. + +`if CONDITION CLAUSE' + This clause executes the following loop clause only if the + specified condition is true. The following CLAUSE should be an + accumulation, `do', `return', `if', or `unless' clause. Several + clauses may be linked by separating them with `and'. These + clauses may be followed by `else' and a clause or clauses to + execute if the condition was false. The whole construct may + optionally be followed by the word `end' (which may be used to + disambiguate an `else' or `and' in a nested `if'). + + The actual non-`nil' value of the condition form is available by + the name `it' in the "then" part. For example: + + (setq funny-numbers '(6 13 -1)) + => (6 13 -1) + (loop for x below 10 + if (oddp x) + collect x into odds + and if (memq x funny-numbers) return (cdr it) end + else + collect x into evens + finally return (vector odds evens)) + => [(1 3 5 7 9) (0 2 4 6 8)] + (setq funny-numbers '(6 7 13 -1)) + => (6 7 13 -1) + (loop ) + => (13 -1) + + Note the use of `and' to put two clauses into the "then" part, one + of which is itself an `if' clause. Note also that `end', while + normally optional, was necessary here to make it clear that the + `else' refers to the outermost `if' clause. In the first case, + the loop returns a vector of lists of the odd and even values of + X. In the second case, the odd number 7 is one of the + `funny-numbers' so the loop returns early; the actual returned + value is based on the result of the `memq' call. + +`when CONDITION CLAUSE' + This clause is just a synonym for `if'. + +`unless CONDITION CLAUSE' + The `unless' clause is just like `if' except that the sense of the + condition is reversed. + +`named NAME' + This clause gives a name other than `nil' to the implicit block + surrounding the loop. The NAME is the symbol to be used as the + block name. + +`initially [do] FORMS...' + This keyword introduces one or more Lisp forms which will be + executed before the loop itself begins (but after any variables + requested by `for' or `with' have been bound to their initial + values). `initially' clauses can appear anywhere; if there are + several, they are executed in the order they appear in the loop. + The keyword `do' is optional. + +`finally [do] FORMS...' + This introduces Lisp forms which will be executed after the loop + finishes (say, on request of a `for' or `while'). `initially' and + `finally' clauses may appear anywhere in the loop construct, but + they are executed (in the specified order) at the beginning or + end, respectively, of the loop. + +`finally return FORM' + This says that FORM should be executed after the loop is done to + obtain a return value. (Without this, or some other clause like + `collect' or `return', the loop will simply return `nil'.) + Variables bound by `for', `with', or `into' will still contain + their final values when FORM is executed. + +`do FORMS...' + The word `do' may be followed by any number of Lisp expressions + which are executed as an implicit `progn' in the body of the loop. + Many of the examples in this section illustrate the use of `do'. + +`return FORM' + This clause causes the loop to return immediately. The following + Lisp form is evaluated to give the return value of the `loop' + form. The `finally' clauses, if any, are not executed. Of + course, `return' is generally used inside an `if' or `unless', as + its use in a top-level loop clause would mean the loop would never + get to "loop" more than once. + + The clause `return FORM' is equivalent to `do (return FORM)' (or + `return-from' if the loop was named). The `return' clause is + implemented a bit more efficiently, though. + + While there is no high-level way to add user extensions to `loop' +(comparable to `defsetf' for `setf', say), this package does offer two +properties called `cl-loop-handler' and `cl-loop-for-handler' which are +functions to be called when a given symbol is encountered as a +top-level loop clause or `for' clause, respectively. Consult the +source code in file `cl-macs.el' for details. + + This package's `loop' macro is compatible with that of Common Lisp, +except that a few features are not implemented: `loop-finish' and +data-type specifiers. Naturally, the `for' clauses which iterate over +keymaps, overlays, intervals, frames, windows, and buffers are +Emacs-specific extensions. + + +File: cl.info, Node: Multiple Values, Prev: Loop Facility, Up: Control Structure + +5.8 Multiple Values +=================== + +Common Lisp functions can return zero or more results. Emacs Lisp +functions, by contrast, always return exactly one result. This package +makes no attempt to emulate Common Lisp multiple return values; Emacs +versions of Common Lisp functions that return more than one value +either return just the first value (as in `compiler-macroexpand') or +return a list of values (as in `get-setf-method'). This package _does_ +define placeholders for the Common Lisp functions that work with +multiple values, but in Emacs Lisp these functions simply operate on +lists instead. The `values' form, for example, is a synonym for `list' +in Emacs. + + -- Special Form: multiple-value-bind (var...) values-form forms... + This form evaluates VALUES-FORM, which must return a list of + values. It then binds the VARs to these respective values, as if + by `let', and then executes the body FORMS. If there are more + VARs than values, the extra VARs are bound to `nil'. If there are + fewer VARs than values, the excess values are ignored. + + -- Special Form: multiple-value-setq (var...) form + This form evaluates FORM, which must return a list of values. It + then sets the VARs to these respective values, as if by `setq'. + Extra VARs or values are treated the same as in + `multiple-value-bind'. + + The older Quiroz package attempted a more faithful (but still +imperfect) emulation of Common Lisp multiple values. The old method +"usually" simulated true multiple values quite well, but under certain +circumstances would leave spurious return values in memory where a +later, unrelated `multiple-value-bind' form would see them. + + Since a perfect emulation is not feasible in Emacs Lisp, this +package opts to keep it as simple and predictable as possible. + + +File: cl.info, Node: Macros, Next: Declarations, Prev: Control Structure, Up: Top + +6 Macros +******** + +This package implements the various Common Lisp features of `defmacro', +such as destructuring, `&environment', and `&body'. Top-level `&whole' +is not implemented for `defmacro' due to technical difficulties. *Note +Argument Lists::. + + Destructuring is made available to the user by way of the following +macro: + + -- Special Form: destructuring-bind arglist expr forms... + This macro expands to code which executes FORMS, with the + variables in ARGLIST bound to the list of values returned by EXPR. + The ARGLIST can include all the features allowed for `defmacro' + argument lists, including destructuring. (The `&environment' + keyword is not allowed.) The macro expansion will signal an error + if EXPR returns a list of the wrong number of arguments or with + incorrect keyword arguments. + + This package also includes the Common Lisp `define-compiler-macro' +facility, which allows you to define compile-time expansions and +optimizations for your functions. + + -- Special Form: define-compiler-macro name arglist forms... + This form is similar to `defmacro', except that it only expands + calls to NAME at compile-time; calls processed by the Lisp + interpreter are not expanded, nor are they expanded by the + `macroexpand' function. + + The argument list may begin with a `&whole' keyword and a + variable. This variable is bound to the macro-call form itself, + i.e., to a list of the form `(NAME ARGS...)'. If the macro + expander returns this form unchanged, then the compiler treats it + as a normal function call. This allows compiler macros to work as + optimizers for special cases of a function, leaving complicated + cases alone. + + For example, here is a simplified version of a definition that + appears as a standard part of this package: + + (define-compiler-macro member* (&whole form a list &rest keys) + (if (and (null keys) + (eq (car-safe a) 'quote) + (not (floatp-safe (cadr a)))) + (list 'memq a list) + form)) + + This definition causes `(member* A LIST)' to change to a call to + the faster `memq' in the common case where A is a + non-floating-point constant; if A is anything else, or if there + are any keyword arguments in the call, then the original `member*' + call is left intact. (The actual compiler macro for `member*' + optimizes a number of other cases, including common `:test' + predicates.) + + -- Function: compiler-macroexpand form + This function is analogous to `macroexpand', except that it + expands compiler macros rather than regular macros. It returns + FORM unchanged if it is not a call to a function for which a + compiler macro has been defined, or if that compiler macro decided + to punt by returning its `&whole' argument. Like `macroexpand', + it expands repeatedly until it reaches a form for which no further + expansion is possible. + + *Note Macro Bindings::, for descriptions of the `macrolet' and +`symbol-macrolet' forms for making "local" macro definitions. + + +File: cl.info, Node: Declarations, Next: Symbols, Prev: Macros, Up: Top + +7 Declarations +************** + +Common Lisp includes a complex and powerful "declaration" mechanism +that allows you to give the compiler special hints about the types of +data that will be stored in particular variables, and about the ways +those variables and functions will be used. This package defines +versions of all the Common Lisp declaration forms: `declare', +`locally', `proclaim', `declaim', and `the'. + + Most of the Common Lisp declarations are not currently useful in +Emacs Lisp, as the byte-code system provides little opportunity to +benefit from type information, and `special' declarations are redundant +in a fully dynamically-scoped Lisp. A few declarations are meaningful +when the optimizing Emacs 19 byte compiler is being used, however. +Under the earlier non-optimizing compiler, these declarations will +effectively be ignored. + + -- Function: proclaim decl-spec + This function records a "global" declaration specified by + DECL-SPEC. Since `proclaim' is a function, DECL-SPEC is evaluated + and thus should normally be quoted. + + -- Special Form: declaim decl-specs... + This macro is like `proclaim', except that it takes any number of + DECL-SPEC arguments, and the arguments are unevaluated and + unquoted. The `declaim' macro also puts an `(eval-when (compile + load eval) ...)' around the declarations so that they will be + registered at compile-time as well as at run-time. (This is vital, + since normally the declarations are meant to influence the way the + compiler treats the rest of the file that contains the `declaim' + form.) + + -- Special Form: declare decl-specs... + This macro is used to make declarations within functions and other + code. Common Lisp allows declarations in various locations, + generally at the beginning of any of the many "implicit `progn's" + throughout Lisp syntax, such as function bodies, `let' bodies, + etc. Currently the only declaration understood by `declare' is + `special'. + + -- Special Form: locally declarations... forms... + In this package, `locally' is no different from `progn'. + + -- Special Form: the type form + Type information provided by `the' is ignored in this package; in + other words, `(the TYPE FORM)' is equivalent to FORM. Future + versions of the optimizing byte-compiler may make use of this + information. + + For example, `mapcar' can map over both lists and arrays. It is + hard for the compiler to expand `mapcar' into an in-line loop + unless it knows whether the sequence will be a list or an array + ahead of time. With `(mapcar 'car (the vector foo))', a future + compiler would have enough information to expand the loop in-line. + For now, Emacs Lisp will treat the above code as exactly equivalent + to `(mapcar 'car foo)'. + + Each DECL-SPEC in a `proclaim', `declaim', or `declare' should be a +list beginning with a symbol that says what kind of declaration it is. +This package currently understands `special', `inline', `notinline', +`optimize', and `warn' declarations. (The `warn' declaration is an +extension of standard Common Lisp.) Other Common Lisp declarations, +such as `type' and `ftype', are silently ignored. + +`special' + Since all variables in Emacs Lisp are "special" (in the Common + Lisp sense), `special' declarations are only advisory. They + simply tell the optimizing byte compiler that the specified + variables are intentionally being referred to without being bound + in the body of the function. The compiler normally emits warnings + for such references, since they could be typographical errors for + references to local variables. + + The declaration `(declare (special VAR1 VAR2))' is equivalent to + `(defvar VAR1) (defvar VAR2)' in the optimizing compiler, or to + nothing at all in older compilers (which do not warn for non-local + references). + + In top-level contexts, it is generally better to write `(defvar + VAR)' than `(declaim (special VAR))', since `defvar' makes your + intentions clearer. But the older byte compilers can not handle + `defvar's appearing inside of functions, while `(declare (special + VAR))' takes care to work correctly with all compilers. + +`inline' + The `inline' DECL-SPEC lists one or more functions whose bodies + should be expanded "in-line" into calling functions whenever the + compiler is able to arrange for it. For example, the Common Lisp + function `cadr' is declared `inline' by this package so that the + form `(cadr X)' will expand directly into `(car (cdr X))' when it + is called in user functions, for a savings of one (relatively + expensive) function call. + + The following declarations are all equivalent. Note that the + `defsubst' form is a convenient way to define a function and + declare it inline all at once, but it is available only in Emacs + 19. + + (declaim (inline foo bar)) + (eval-when (compile load eval) (proclaim '(inline foo bar))) + (proclaim-inline foo bar) ; XEmacs only + (defsubst foo (...) ...) ; instead of defun; Emacs 19 only + + *Please note:* This declaration remains in effect after the + containing source file is done. It is correct to use it to + request that a function you have defined should be inlined, but it + is impolite to use it to request inlining of an external function. + + In Common Lisp, it is possible to use `(declare (inline ...))' + before a particular call to a function to cause just that call to + be inlined; the current byte compilers provide no way to implement + this, so `(declare (inline ...))' is currently ignored by this + package. + +`notinline' + The `notinline' declaration lists functions which should not be + inlined after all; it cancels a previous `inline' declaration. + +`optimize' + This declaration controls how much optimization is performed by + the compiler. Naturally, it is ignored by the earlier + non-optimizing compilers. + + The word `optimize' is followed by any number of lists like + `(speed 3)' or `(safety 2)'. Common Lisp defines several + optimization "qualities"; this package ignores all but `speed' and + `safety'. The value of a quality should be an integer from 0 to + 3, with 0 meaning "unimportant" and 3 meaning "very important." + The default level for both qualities is 1. + + In this package, with the Emacs 19 optimizing compiler, the + `speed' quality is tied to the `byte-compile-optimize' flag, which + is set to `nil' for `(speed 0)' and to `t' for higher settings; + and the `safety' quality is tied to the + `byte-compile-delete-errors' flag, which is set to `t' for + `(safety 3)' and to `nil' for all lower settings. (The latter + flag controls whether the compiler is allowed to optimize out code + whose only side-effect could be to signal an error, e.g., + rewriting `(progn foo bar)' to `bar' when it is not known whether + `foo' will be bound at run-time.) + + Note that even compiling with `(safety 0)', the Emacs byte-code + system provides sufficient checking to prevent real harm from + being done. For example, barring serious bugs in Emacs itself, + Emacs will not crash with a segmentation fault just because of an + error in a fully-optimized Lisp program. + + The `optimize' declaration is normally used in a top-level + `proclaim' or `declaim' in a file; Common Lisp allows it to be + used with `declare' to set the level of optimization locally for a + given form, but this will not work correctly with the current + version of the optimizing compiler. (The `declare' will set the + new optimization level, but that level will not automatically be + unset after the enclosing form is done.) + +`warn' + This declaration controls what sorts of warnings are generated by + the byte compiler. Again, only the optimizing compiler generates + warnings. The word `warn' is followed by any number of "warning + qualities," similar in form to optimization qualities. The + currently supported warning types are `redefine', `callargs', + `unresolved', and `free-vars'; in the current system, a value of 0 + will disable these warnings and any higher value will enable them. + See the documentation for the optimizing byte compiler for details. + + +File: cl.info, Node: Symbols, Next: Numbers, Prev: Declarations, Up: Top + +8 Symbols +********* + +This package defines several symbol-related features that were missing +from Emacs Lisp. + +* Menu: + +* Property Lists:: `getf', `remf' +* Creating Symbols:: `gensym', `gentemp' + + +File: cl.info, Node: Property Lists, Next: Creating Symbols, Prev: Symbols, Up: Symbols + +8.1 Property Lists +================== + +These functions augment the standard Emacs Lisp functions `get' and +`put' for operating on properties attached to objects. There are also +functions for working with property lists as first-class data +structures not attached to particular objects. + + -- Function: getf place property &optional default + This function scans the list PLACE as if it were a property list, + i.e., a list of alternating property names and values. If an + even-numbered element of PLACE is found which is `eq' to PROPERTY, + the following odd-numbered element is returned. Otherwise, + DEFAULT is returned (or `nil' if no default is given). + + In particular, + + (get sym prop) == (getf (symbol-plist sym) prop) + + It is legal to use `getf' as a `setf' place, in which case its + PLACE argument must itself be a legal `setf' place. The DEFAULT + argument, if any, is ignored in this context. The effect is to + change (via `setcar') the value cell in the list that corresponds + to PROPERTY, or to cons a new property-value pair onto the list if + the property is not yet present. + + (put sym prop val) == (setf (getf (symbol-plist sym) prop) val) + + The `get' function is also `setf'-able. The fact that `default' + is ignored can sometimes be useful: + + (incf (get 'foo 'usage-count 0)) + + Here, symbol `foo''s `usage-count' property is incremented if it + exists, or set to 1 (an incremented 0) otherwise. + + When not used as a `setf' form, `getf' is just a regular function + and its PLACE argument can actually be any Lisp expression. + + -- Special Form: remf place property + This macro removes the property-value pair for PROPERTY from the + property list stored at PLACE, which is any `setf'-able place + expression. It returns true if the property was found. Note that + if PROPERTY happens to be first on the list, this will effectively + do a `(setf PLACE (cddr PLACE))', whereas if it occurs later, this + simply uses `setcdr' to splice out the property and value cells. + + +File: cl.info, Node: Creating Symbols, Prev: Property Lists, Up: Symbols + +8.2 Creating Symbols +==================== + +These functions create unique symbols, typically for use as temporary +variables. + + -- Function: gensym &optional x + This function creates a new, uninterned symbol (using + `make-symbol') with a unique name. (The name of an uninterned + symbol is relevant only if the symbol is printed.) By default, + the name is generated from an increasing sequence of numbers, + `G1000', `G1001', `G1002', etc. If the optional argument X is a + string, that string is used as a prefix instead of `G'. + Uninterned symbols are used in macro expansions for temporary + variables, to ensure that their names will not conflict with + "real" variables in the user's code. + + -- Variable: *gensym-counter* + This variable holds the counter used to generate `gensym' names. + It is incremented after each use by `gensym'. In Common Lisp this + is initialized with 0, but this package initializes it with a + random (time-dependent) value to avoid trouble when two files that + each used `gensym' in their compilation are loaded together. + + *XEmacs note:* As of XEmacs 21.0, an uninterned symbol remains + uninterned even after being dumped to bytecode. Older versions of + Emacs didn't distinguish the printed representation of interned + and uninterned symbols, so their names had to be treated more + carefully. + + -- Function: gentemp &optional x + This function is like `gensym', except that it produces a new + _interned_ symbol. If the symbol that is generated already + exists, the function keeps incrementing the counter and trying + again until a new symbol is generated. + + The Quiroz `cl.el' package also defined a `defkeyword' form for +creating self-quoting keyword symbols. This package automatically +creates all keywords that are called for by `&key' argument specifiers, +and discourages the use of keywords as data unrelated to keyword +arguments, so the `defkeyword' form has been discontinued. + + +File: cl.info, Node: Numbers, Next: Sequences, Prev: Symbols, Up: Top + +9 Numbers +********* + +This section defines a few simple Common Lisp operations on numbers +which were left out of Emacs Lisp. + +* Menu: + +* Predicates on Numbers:: `plusp', `oddp', `floatp-safe', etc. +* Numerical Functions:: `abs', `expt', `floor*', etc. +* Random Numbers:: `random*', `make-random-state' +* Implementation Parameters:: `most-positive-fixnum', `most-positive-float' + + +File: cl.info, Node: Predicates on Numbers, Next: Numerical Functions, Prev: Numbers, Up: Numbers + +9.1 Predicates on Numbers +========================= + +These functions return `t' if the specified condition is true of the +numerical argument, or `nil' otherwise. + + -- Function: plusp number + This predicate tests whether NUMBER is positive. It is an error + if the argument is not a number. + + -- Function: minusp number + This predicate tests whether NUMBER is negative. It is an error + if the argument is not a number. + + -- Function: oddp integer + This predicate tests whether INTEGER is odd. It is an error if + the argument is not an integer. + + -- Function: evenp integer + This predicate tests whether INTEGER is even. It is an error if + the argument is not an integer. + + -- Function: floatp-safe object + This predicate tests whether OBJECT is a floating-point number. + On systems that support floating-point, this is equivalent to + `floatp'. On other systems, this always returns `nil'. + + +File: cl.info, Node: Numerical Functions, Next: Random Numbers, Prev: Predicates on Numbers, Up: Numbers + +9.2 Numerical Functions +======================= + +These functions perform various arithmetic operations on numbers. + + -- Function: abs number + This function returns the absolute value of NUMBER. (Newer + versions of Emacs provide this as a built-in function; this package + defines `abs' only for Emacs 18 versions which don't provide it as + a primitive.) + + -- Function: expt base power + This function returns BASE raised to the power of NUMBER. (Newer + versions of Emacs provide this as a built-in function; this + package defines `expt' only for Emacs 18 versions which don't + provide it as a primitive.) + + -- Function: gcd &rest integers + This function returns the Greatest Common Divisor of the arguments. + For one argument, it returns the absolute value of that argument. + For zero arguments, it returns zero. + + -- Function: lcm &rest integers + This function returns the Least Common Multiple of the arguments. + For one argument, it returns the absolute value of that argument. + For zero arguments, it returns one. + + -- Function: isqrt integer + This function computes the "integer square root" of its integer + argument, i.e., the greatest integer less than or equal to the true + square root of the argument. + + -- Function: floor* number &optional divisor + This function implements the Common Lisp `floor' function. It is + called `floor*' to avoid name conflicts with the simpler `floor' + function built-in to Emacs 19. + + With one argument, `floor*' returns a list of two numbers: The + argument rounded down (toward minus infinity) to an integer, and + the "remainder" which would have to be added back to the first + return value to yield the argument again. If the argument is an + integer X, the result is always the list `(X 0)'. If the argument + is an Emacs 19 floating-point number, the first result is a Lisp + integer and the second is a Lisp float between 0 (inclusive) and 1 + (exclusive). + + With two arguments, `floor*' divides NUMBER by DIVISOR, and + returns the floor of the quotient and the corresponding remainder + as a list of two numbers. If `(floor* X Y)' returns `(Q R)', then + `Q*Y + R = X', with R between 0 (inclusive) and R (exclusive). + Also, note that `(floor* X)' is exactly equivalent to `(floor* X + 1)'. + + This function is entirely compatible with Common Lisp's `floor' + function, except that it returns the two results in a list since + Emacs Lisp does not support multiple-valued functions. + + -- Function: ceiling* number &optional divisor + This function implements the Common Lisp `ceiling' function, which + is analogous to `floor' except that it rounds the argument or + quotient of the arguments up toward plus infinity. The remainder + will be between 0 and minus R. + + -- Function: truncate* number &optional divisor + This function implements the Common Lisp `truncate' function, + which is analogous to `floor' except that it rounds the argument + or quotient of the arguments toward zero. Thus it is equivalent + to `floor*' if the argument or quotient is positive, or to + `ceiling*' otherwise. The remainder has the same sign as NUMBER. + + -- Function: round* number &optional divisor + This function implements the Common Lisp `round' function, which + is analogous to `floor' except that it rounds the argument or + quotient of the arguments to the nearest integer. In the case of + a tie (the argument or quotient is exactly halfway between two + integers), it rounds to the even integer. + + -- Function: mod* number divisor + This function returns the same value as the second return value of + `floor'. + + -- Function: rem* number divisor + This function returns the same value as the second return value of + `truncate'. + + These definitions are compatible with those in the Quiroz `cl.el' +package, except that this package appends `*' to certain function names +to avoid conflicts with existing Emacs 19 functions, and that the +mechanism for returning multiple values is different. + + +File: cl.info, Node: Random Numbers, Next: Implementation Parameters, Prev: Numerical Functions, Up: Numbers + +9.3 Random Numbers +================== + +This package also provides an implementation of the Common Lisp random +number generator. It uses its own additive-congruential algorithm, +which is much more likely to give statistically clean random numbers +than the simple generators supplied by many operating systems. + + -- Function: random* number &optional state + This function returns a random nonnegative number less than + NUMBER, and of the same type (either integer or floating-point). + The STATE argument should be a `random-state' object which holds + the state of the random number generator. The function modifies + this state object as a side effect. If STATE is omitted, it + defaults to the variable `*random-state*', which contains a + pre-initialized `random-state' object. + + -- Variable: *random-state* + This variable contains the system "default" `random-state' object, + used for calls to `random*' that do not specify an alternative + state object. Since any number of programs in the Emacs process + may be accessing `*random-state*' in interleaved fashion, the + sequence generated from this variable will be irreproducible for + all intents and purposes. + + -- Function: make-random-state &optional state + This function creates or copies a `random-state' object. If STATE + is omitted or `nil', it returns a new copy of `*random-state*'. + This is a copy in the sense that future sequences of calls to + `(random* N)' and `(random* N S)' (where S is the new random-state + object) will return identical sequences of random numbers. + + If STATE is a `random-state' object, this function returns a copy + of that object. If STATE is `t', this function returns a new + `random-state' object seeded from the date and time. As an + extension to Common Lisp, STATE may also be an integer in which + case the new object is seeded from that integer; each different + integer seed will result in a completely different sequence of + random numbers. + + It is legal to print a `random-state' object to a buffer or file + and later read it back with `read'. If a program wishes to use a + sequence of pseudo-random numbers which can be reproduced later + for debugging, it can call `(make-random-state t)' to get a new + sequence, then print this sequence to a file. When the program is + later rerun, it can read the original run's random-state from the + file. + + -- Function: random-state-p object + This predicate returns `t' if OBJECT is a `random-state' object, + or `nil' otherwise. + + +File: cl.info, Node: Implementation Parameters, Prev: Random Numbers, Up: Numbers + +9.4 Implementation Parameters +============================= + +This package defines several useful constants having to with numbers. + + -- Variable: most-positive-fixnum + This constant equals the largest value a Lisp integer can hold. + It is typically `2^23-1' or `2^25-1'. + + -- Variable: most-negative-fixnum + This constant equals the smallest (most negative) value a Lisp + integer can hold. + + The following parameters have to do with floating-point numbers. +This package determines their values by exercising the computer's +floating-point arithmetic in various ways. Because this operation +might be slow, the code for initializing them is kept in a separate +function that must be called before the parameters can be used. + + -- Function: cl-float-limits + This function makes sure that the Common Lisp floating-point + parameters like `most-positive-float' have been initialized. + Until it is called, these parameters will be `nil'. If this + version of Emacs does not support floats (e.g., most versions of + Emacs 18), the parameters will remain `nil'. If the parameters + have already been initialized, the function returns immediately. + + The algorithm makes assumptions that will be valid for most modern + machines, but will fail if the machine's arithmetic is extremely + unusual, e.g., decimal. + + Since true Common Lisp supports up to four different floating-point +precisions, it has families of constants like +`most-positive-single-float', `most-positive-double-float', +`most-positive-long-float', and so on. Emacs has only one +floating-point precision, so this package omits the precision word from +the constants' names. + + -- Variable: most-positive-float + This constant equals the largest value a Lisp float can hold. For + those systems whose arithmetic supports infinities, this is the + largest _finite_ value. For IEEE machines, the value is + approximately `1.79e+308'. + + -- Variable: most-negative-float + This constant equals the most-negative value a Lisp float can hold. + (It is assumed to be equal to `(- most-positive-float)'.) + + -- Variable: least-positive-float + This constant equals the smallest Lisp float value greater than + zero. For IEEE machines, it is about `4.94e-324' if denormals are + supported or `2.22e-308' if not. + + -- Variable: least-positive-normalized-float + This constant equals the smallest _normalized_ Lisp float greater + than zero, i.e., the smallest value for which IEEE denormalization + will not result in a loss of precision. For IEEE machines, this + value is about `2.22e-308'. For machines that do not support the + concept of denormalization and gradual underflow, this constant + will always equal `least-positive-float'. + + -- Variable: least-negative-float + This constant is the negative counterpart of + `least-positive-float'. + + -- Variable: least-negative-normalized-float + This constant is the negative counterpart of + `least-positive-normalized-float'. + + -- Variable: float-epsilon + This constant is the smallest positive Lisp float that can be added + to 1.0 to produce a distinct value. Adding a smaller number to 1.0 + will yield 1.0 again due to roundoff. For IEEE machines, epsilon + is about `2.22e-16'. + + -- Variable: float-negative-epsilon + This is the smallest positive value that can be subtracted from + 1.0 to produce a distinct value. For IEEE machines, it is about + `1.11e-16'. + + +File: cl.info, Node: Sequences, Next: Lists, Prev: Numbers, Up: Top + +10 Sequences +************ + +Common Lisp defines a number of functions that operate on "sequences", +which are either lists, strings, or vectors. Emacs Lisp includes a few +of these, notably `elt' and `length'; this package defines most of the +rest. + +* Menu: + +* Sequence Basics:: Arguments shared by all sequence functions +* Mapping over Sequences:: `mapcar*', `mapcan', `map', `every', etc. +* Sequence Functions:: `subseq', `remove*', `substitute', etc. +* Searching Sequences:: `find', `position', `count', `search', etc. +* Sorting Sequences:: `sort*', `stable-sort', `merge' + + +File: cl.info, Node: Sequence Basics, Next: Mapping over Sequences, Prev: Sequences, Up: Sequences + +10.1 Sequence Basics +==================== + +Many of the sequence functions take keyword arguments; *note Argument +Lists::. All keyword arguments are optional and, if specified, may +appear in any order. + + The `:key' argument should be passed either `nil', or a function of +one argument. This key function is used as a filter through which the +elements of the sequence are seen; for example, `(find x y :key 'car)' +is similar to `(assoc* x y)': It searches for an element of the list +whose `car' equals `x', rather than for an element which equals `x' +itself. If `:key' is omitted or `nil', the filter is effectively the +identity function. + + The `:test' and `:test-not' arguments should be either `nil', or +functions of two arguments. The test function is used to compare two +sequence elements, or to compare a search value with sequence elements. +(The two values are passed to the test function in the same order as +the original sequence function arguments from which they are derived, +or, if they both come from the same sequence, in the same order as they +appear in that sequence.) The `:test' argument specifies a function +which must return true (non-`nil') to indicate a match; instead, you +may use `:test-not' to give a function which returns _false_ to +indicate a match. The default test function is `:test 'eql'. + + Many functions which take ITEM and `:test' or `:test-not' arguments +also come in `-if' and `-if-not' varieties, where a PREDICATE function +is passed instead of ITEM, and sequence elements match if the predicate +returns true on them (or false in the case of `-if-not'). For example: + + (remove* 0 seq :test '=) == (remove-if 'zerop seq) + +to remove all zeros from sequence `seq'. + + Some operations can work on a subsequence of the argument sequence; +these function take `:start' and `:end' arguments which default to zero +and the length of the sequence, respectively. Only elements between +START (inclusive) and END (exclusive) are affected by the operation. +The END argument may be passed `nil' to signify the length of the +sequence; otherwise, both START and END must be integers, with `0 <= +START <= END <= (length SEQ)'. If the function takes two sequence +arguments, the limits are defined by keywords `:start1' and `:end1' for +the first, and `:start2' and `:end2' for the second. + + A few functions accept a `:from-end' argument, which, if non-`nil', +causes the operation to go from right-to-left through the sequence +instead of left-to-right, and a `:count' argument, which specifies an +integer maximum number of elements to be removed or otherwise processed. + + The sequence functions make no guarantees about the order in which +the `:test', `:test-not', and `:key' functions are called on various +elements. Therefore, it is a bad idea to depend on side effects of +these functions. For example, `:from-end' may cause the sequence to be +scanned actually in reverse, or it may be scanned forwards but +computing a result "as if" it were scanned backwards. (Some functions, +like `mapcar*' and `every', _do_ specify exactly the order in which the +function is called so side effects are perfectly acceptable in those +cases.) + + Strings in GNU Emacs 19 may contain "text properties" as well as +character data. Except as noted, it is undefined whether or not text +properties are preserved by sequence functions. For example, `(remove* +?A STR)' may or may not preserve the properties of the characters +copied from STR into the result. + + +File: cl.info, Node: Mapping over Sequences, Next: Sequence Functions, Prev: Sequence Basics, Up: Sequences + +10.2 Mapping over Sequences +=========================== + +These functions "map" the function you specify over the elements of +lists or arrays. They are all variations on the theme of the built-in +function `mapcar'. + + -- Function: mapcar* function seq &rest more-seqs + This function calls FUNCTION on successive parallel sets of + elements from its argument sequences. Given a single SEQ argument + it is equivalent to `mapcar'; given N sequences, it calls the + function with the first elements of each of the sequences as the N + arguments to yield the first element of the result list, then with + the second elements, and so on. The mapping stops as soon as the + shortest sequence runs out. The argument sequences may be any + mixture of lists, strings, and vectors; the return sequence is + always a list. + + Common Lisp's `mapcar' accepts multiple arguments but works only + on lists; Emacs Lisp's `mapcar' accepts a single sequence + argument. This package's `mapcar*' works as a compatible superset + of both. + + -- Function: map result-type function seq &rest more-seqs + This function maps FUNCTION over the argument sequences, just like + `mapcar*', but it returns a sequence of type RESULT-TYPE rather + than a list. RESULT-TYPE must be one of the following symbols: + `vector', `string', `list' (in which case the effect is the same + as for `mapcar*'), or `nil' (in which case the results are thrown + away and `map' returns `nil'). + + -- Function: maplist function list &rest more-lists + This function calls FUNCTION on each of its argument lists, then + on the `cdr's of those lists, and so on, until the shortest list + runs out. The results are returned in the form of a list. Thus, + `maplist' is like `mapcar*' except that it passes in the list + pointers themselves rather than the `car's of the advancing + pointers. + + -- Function: mapc function seq &rest more-seqs + This function is like `mapcar*', except that the values returned + by FUNCTION are ignored and thrown away rather than being + collected into a list. The return value of `mapc' is SEQ, the + first sequence. + + -- Function: mapl function list &rest more-lists + This function is like `maplist', except that it throws away the + values returned by FUNCTION. + + -- Function: mapcan function seq &rest more-seqs + This function is like `mapcar*', except that it concatenates the + return values (which must be lists) using `nconc', rather than + simply collecting them into a list. + + -- Function: mapcon function list &rest more-lists + This function is like `maplist', except that it concatenates the + return values using `nconc'. + + -- Function: some predicate seq &rest more-seqs + This function calls PREDICATE on each element of SEQ in turn; if + PREDICATE returns a non-`nil' value, `some' returns that value, + otherwise it returns `nil'. Given several sequence arguments, it + steps through the sequences in parallel until the shortest one + runs out, just as in `mapcar*'. You can rely on the left-to-right + order in which the elements are visited, and on the fact that + mapping stops immediately as soon as PREDICATE returns non-`nil'. + + -- Function: every predicate seq &rest more-seqs + This function calls PREDICATE on each element of the sequence(s) + in turn; it returns `nil' as soon as PREDICATE returns `nil' for + any element, or `t' if the predicate was true for all elements. + + -- Function: notany predicate seq &rest more-seqs + This function calls PREDICATE on each element of the sequence(s) + in turn; it returns `nil' as soon as PREDICATE returns a non-`nil' + value for any element, or `t' if the predicate was `nil' for all + elements. + + -- Function: notevery predicate seq &rest more-seqs + This function calls PREDICATE on each element of the sequence(s) + in turn; it returns a non-`nil' value as soon as PREDICATE returns + `nil' for any element, or `t' if the predicate was true for all + elements. + + -- Function: reduce function seq &key :from-end :start :end + :initial-value :key + This function combines the elements of SEQ using an associative + binary operation. Suppose FUNCTION is `*' and SEQ is the list `(2 + 3 4 5)'. The first two elements of the list are combined with `(* + 2 3) = 6'; this is combined with the next element, `(* 6 4) = 24', + and that is combined with the final element: `(* 24 5) = 120'. + Note that the `*' function happens to be self-reducing, so that + `(* 2 3 4 5)' has the same effect as an explicit call to `reduce'. + + If `:from-end' is true, the reduction is right-associative instead + of left-associative: + + (reduce '- '(1 2 3 4)) + == (- (- (- 1 2) 3) 4) => -8 + (reduce '- '(1 2 3 4) :from-end t) + == (- 1 (- 2 (- 3 4))) => -2 + + If `:key' is specified, it is a function of one argument which is + called on each of the sequence elements in turn. + + If `:initial-value' is specified, it is effectively added to the + front (or rear in the case of `:from-end') of the sequence. The + `:key' function is _not_ applied to the initial value. + + If the sequence, including the initial value, has exactly one + element then that element is returned without ever calling + FUNCTION. If the sequence is empty (and there is no initial + value), then FUNCTION is called with no arguments to obtain the + return value. + + All of these mapping operations can be expressed conveniently in +terms of the `loop' macro. In compiled code, `loop' will be faster +since it generates the loop as in-line code with no function calls. + + +File: cl.info, Node: Sequence Functions, Next: Searching Sequences, Prev: Mapping over Sequences, Up: Sequences + +10.3 Sequence Functions +======================= + +This section describes a number of Common Lisp functions for operating +on sequences. + + -- Function: subseq sequence start &optional end + This function returns a given subsequence of the argument + SEQUENCE, which may be a list, string, or vector. The indices + START and END must be in range, and START must be no greater than + END. If END is omitted, it defaults to the length of the + sequence. The return value is always a copy; it does not share + structure with SEQUENCE. + + As an extension to Common Lisp, START and/or END may be negative, + in which case they represent a distance back from the end of the + sequence. This is for compatibility with Emacs' `substring' + function. Note that `subseq' is the _only_ sequence function that + allows negative START and END. + + You can use `setf' on a `subseq' form to replace a specified range + of elements with elements from another sequence. The replacement + is done as if by `replace', described below. + + -- Function: concatenate result-type &rest seqs + This function concatenates the argument sequences together to form + a result sequence of type RESULT-TYPE, one of the symbols + `vector', `string', or `list'. The arguments are always copied, + even in cases such as `(concatenate 'list '(1 2 3))' where the + result is identical to an argument. + + -- Function: fill seq item &key :start :end + This function fills the elements of the sequence (or the specified + part of the sequence) with the value ITEM. + + -- Function: replace seq1 seq2 &key :start1 :end1 :start2 :end2 + This function copies part of SEQ2 into part of SEQ1. The sequence + SEQ1 is not stretched or resized; the amount of data copied is + simply the shorter of the source and destination (sub)sequences. + The function returns SEQ1. + + If SEQ1 and SEQ2 are `eq', then the replacement will work + correctly even if the regions indicated by the start and end + arguments overlap. However, if SEQ1 and SEQ2 are lists which + share storage but are not `eq', and the start and end arguments + specify overlapping regions, the effect is undefined. + + -- Function: remove* item seq &key :test :test-not :key :count :start + :end :from-end + This returns a copy of SEQ with all elements matching ITEM + removed. The result may share storage with or be `eq' to SEQ in + some circumstances, but the original SEQ will not be modified. + The `:test', `:test-not', and `:key' arguments define the matching + test that is used; by default, elements `eql' to ITEM are removed. + The `:count' argument specifies the maximum number of matching + elements that can be removed (only the leftmost COUNT matches are + removed). The `:start' and `:end' arguments specify a region in + SEQ in which elements will be removed; elements outside that + region are not matched or removed. The `:from-end' argument, if + true, says that elements should be deleted from the end of the + sequence rather than the beginning (this matters only if COUNT was + also specified). + + -- Function: delete* item seq &key :test :test-not :key :count :start + :end :from-end + This deletes all elements of SEQ which match ITEM. It is a + destructive operation. Since Emacs Lisp does not support + stretchable strings or vectors, this is the same as `remove*' for + those sequence types. On lists, `remove*' will copy the list if + necessary to preserve the original list, whereas `delete*' will + splice out parts of the argument list. Compare `append' and + `nconc', which are analogous non-destructive and destructive list + operations in Emacs Lisp. + + The predicate-oriented functions `remove-if', `remove-if-not', +`delete-if', and `delete-if-not' are defined similarly. + + -- Function: delete item list + This MacLisp-compatible function deletes from LIST all elements + which are `equal' to ITEM. The `delete' function is built-in to + Emacs 19; this package defines it equivalently in Emacs 18. + + -- Function: remove item list + This function removes from LIST all elements which are `equal' to + ITEM. This package defines it for symmetry with `delete', even + though `remove' is not built-in to Emacs 19. + + -- Function: remq item list + This function removes from LIST all elements which are `eq' to + ITEM. This package defines it for symmetry with `delq', even + though `remq' is not built-in to Emacs 19. + + -- Function: remove-duplicates seq &key :test :test-not :key :start + :end :from-end + This function returns a copy of SEQ with duplicate elements + removed. Specifically, if two elements from the sequence match + according to the `:test', `:test-not', and `:key' arguments, only + the rightmost one is retained. If `:from-end' is true, the + leftmost one is retained instead. If `:start' or `:end' is + specified, only elements within that subsequence are examined or + removed. + + -- Function: delete-duplicates seq &key :test :test-not :key :start + :end :from-end + This function deletes duplicate elements from SEQ. It is a + destructive version of `remove-duplicates'. + + -- Function: substitute new old seq &key :test :test-not :key :count + :start :end :from-end + This function returns a copy of SEQ, with all elements matching + OLD replaced with NEW. The `:count', `:start', `:end', and + `:from-end' arguments may be used to limit the number of + substitutions made. + + -- Function: nsubstitute new old seq &key :test :test-not :key :count + :start :end :from-end + This is a destructive version of `substitute'; it performs the + substitution using `setcar' or `aset' rather than by returning a + changed copy of the sequence. + + The `substitute-if', `substitute-if-not', `nsubstitute-if', and +`nsubstitute-if-not' functions are defined similarly. For these, a +PREDICATE is given in place of the OLD argument. + + +File: cl.info, Node: Searching Sequences, Next: Sorting Sequences, Prev: Sequence Functions, Up: Sequences + +10.4 Searching Sequences +======================== + +These functions search for elements or subsequences in a sequence. +(See also `member*' and `assoc*'; *note Lists::.) + + -- Function: find item seq &key :test :test-not :key :start :end + :from-end + This function searches SEQ for an element matching ITEM. If it + finds a match, it returns the matching element. Otherwise, it + returns `nil'. It returns the leftmost match, unless `:from-end' + is true, in which case it returns the rightmost match. The + `:start' and `:end' arguments may be used to limit the range of + elements that are searched. + + -- Function: position item seq &key :test :test-not :key :start :end + :from-end + This function is like `find', except that it returns the integer + position in the sequence of the matching item rather than the item + itself. The position is relative to the start of the sequence as + a whole, even if `:start' is non-zero. The function returns `nil' + if no matching element was found. + + -- Function: count item seq &key :test :test-not :key :start :end + This function returns the number of elements of SEQ which match + ITEM. The result is always a nonnegative integer. + + The `find-if', `find-if-not', `position-if', `position-if-not', +`count-if', and `count-if-not' functions are defined similarly. + + -- Function: mismatch seq1 seq2 &key :test :test-not :key :start1 + :end1 :start2 :end2 :from-end + This function compares the specified parts of SEQ1 and SEQ2. If + they are the same length and the corresponding elements match + (according to `:test', `:test-not', and `:key'), the function + returns `nil'. If there is a mismatch, the function returns the + index (relative to SEQ1) of the first mismatching element. This + will be the leftmost pair of elements which do not match, or the + position at which the shorter of the two otherwise-matching + sequences runs out. + + If `:from-end' is true, then the elements are compared from right + to left starting at `(1- END1)' and `(1- END2)'. If the sequences + differ, then one plus the index of the rightmost difference + (relative to SEQ1) is returned. + + An interesting example is `(mismatch str1 str2 :key 'upcase)', + which compares two strings case-insensitively. + + -- Function: search seq1 seq2 &key :test :test-not :key :from-end + :start1 :end1 :start2 :end2 + This function searches SEQ2 for a subsequence that matches SEQ1 + (or part of it specified by `:start1' and `:end1'.) Only matches + which fall entirely within the region defined by `:start2' and + `:end2' will be considered. The return value is the index of the + leftmost element of the leftmost match, relative to the start of + SEQ2, or `nil' if no matches were found. If `:from-end' is true, + the function finds the _rightmost_ matching subsequence. + + +File: cl.info, Node: Sorting Sequences, Prev: Searching Sequences, Up: Sequences + +10.5 Sorting Sequences +====================== + + -- Function: sort* seq predicate &key :key + This function sorts SEQ into increasing order as determined by + using PREDICATE to compare pairs of elements. PREDICATE should + return true (non-`nil') if and only if its first argument is less + than (not equal to) its second argument. For example, `<' and + `string-lessp' are suitable predicate functions for sorting + numbers and strings, respectively; `>' would sort numbers into + decreasing rather than increasing order. + + This function differs from Emacs' built-in `sort' in that it can + operate on any type of sequence, not just lists. Also, it accepts + a `:key' argument which is used to preprocess data fed to the + PREDICATE function. For example, + + (setq data (sort data 'string-lessp :key 'downcase)) + + sorts DATA, a sequence of strings, into increasing alphabetical + order without regard to case. A `:key' function of `car' would be + useful for sorting association lists. + + The `sort*' function is destructive; it sorts lists by actually + rearranging the `cdr' pointers in suitable fashion. + + -- Function: stable-sort seq predicate &key :key + This function sorts SEQ "stably", meaning two elements which are + equal in terms of PREDICATE are guaranteed not to be rearranged + out of their original order by the sort. + + In practice, `sort*' and `stable-sort' are equivalent in Emacs + Lisp because the underlying `sort' function is stable by default. + However, this package reserves the right to use non-stable methods + for `sort*' in the future. + + -- Function: merge type seq1 seq2 predicate &key :key + This function merges two sequences SEQ1 and SEQ2 by interleaving + their elements. The result sequence, of type TYPE (in the sense + of `concatenate'), has length equal to the sum of the lengths of + the two input sequences. The sequences may be modified + destructively. Order of elements within SEQ1 and SEQ2 is + preserved in the interleaving; elements of the two sequences are + compared by PREDICATE (in the sense of `sort') and the lesser + element goes first in the result. When elements are equal, those + from SEQ1 precede those from SEQ2 in the result. Thus, if SEQ1 + and SEQ2 are both sorted according to PREDICATE, then the result + will be a merged sequence which is (stably) sorted according to + PREDICATE. + + +File: cl.info, Node: Lists, Next: Hash Tables, Prev: Sequences, Up: Top + +11 Lists +******** + +The functions described here operate on lists. + +* Menu: + +* List Functions:: `caddr', `first', `last', `list*', etc. +* Substitution of Expressions:: `subst', `sublis', etc. +* Lists as Sets:: `member*', `adjoin', `union', etc. +* Association Lists:: `assoc*', `rassoc*', `acons', `pairlis' + + +File: cl.info, Node: List Functions, Next: Substitution of Expressions, Prev: Lists, Up: Lists + +11.1 List Functions +=================== + +This section describes a number of simple operations on lists, i.e., +chains of cons cells. + + -- Function: caddr x + This function is equivalent to `(car (cdr (cdr X)))'. Likewise, + this package defines all 28 `cXXXr' functions where XXX is up to + four `a's and/or `d's. All of these functions are `setf'-able, + and calls to them are expanded inline by the byte-compiler for + maximum efficiency. + + -- Function: first x + This function is a synonym for `(car X)'. Likewise, the functions + `second', `third', ..., through `tenth' return the given element + of the list X. + + -- Function: rest x + This function is a synonym for `(cdr X)'. + + -- Function: endp x + Common Lisp defines this function to act like `null', but + signalling an error if `x' is neither a `nil' nor a cons cell. + This package simply defines `endp' as a synonym for `null'. + + -- Function: list-length x + This function returns the length of list X, exactly like `(length + X)', except that if X is a circular list (where the cdr-chain + forms a loop rather than terminating with `nil'), this function + returns `nil'. (The regular `length' function would get stuck if + given a circular list.) + + -- Function: last x &optional n + This function returns the last cons, or the Nth-to-last cons, of + the list X. If N is omitted it defaults to 1. The "last cons" + means the first cons cell of the list whose `cdr' is not another + cons cell. (For normal lists, the `cdr' of the last cons will be + `nil'.) This function returns `nil' if X is `nil' or shorter than + N. Note that the last _element_ of the list is `(car (last X))'. + + -- Function: butlast x &optional n + This function returns the list X with the last element, or the + last N elements, removed. If N is greater than zero it makes a + copy of the list so as not to damage the original list. In + general, `(append (butlast X N) (last X N))' will return a list + equal to X. + + -- Function: nbutlast x &optional n + This is a version of `butlast' that works by destructively + modifying the `cdr' of the appropriate element, rather than making + a copy of the list. + + -- Function: list* arg &rest others + This function constructs a list of its arguments. The final + argument becomes the `cdr' of the last cell constructed. Thus, + `(list* A B C)' is equivalent to `(cons A (cons B C))', and + `(list* A B nil)' is equivalent to `(list A B)'. + + (Note that this function really is called `list*' in Common Lisp; + it is not a name invented for this package like `member*' or + `defun*'.) + + -- Function: ldiff list sublist + If SUBLIST is a sublist of LIST, i.e., is `eq' to one of the cons + cells of LIST, then this function returns a copy of the part of + LIST up to but not including SUBLIST. For example, `(ldiff x + (cddr x))' returns the first two elements of the list `x'. The + result is a copy; the original LIST is not modified. If SUBLIST + is not a sublist of LIST, a copy of the entire LIST is returned. + + -- Function: copy-list list + This function returns a copy of the list LIST. It copies dotted + lists like `(1 2 . 3)' correctly. + + -- Function: copy-tree x &optional vecp + This function returns a copy of the tree of cons cells X. Unlike + `copy-sequence' (and its alias `copy-list'), which copies only + along the `cdr' direction, this function copies (recursively) + along both the `car' and the `cdr' directions. If X is not a cons + cell, the function simply returns X unchanged. If the optional + VECP argument is true, this function copies vectors (recursively) + as well as cons cells. + + -- Function: tree-equal x y &key :test :test-not :key + This function compares two trees of cons cells. If X and Y are + both cons cells, their `car's and `cdr's are compared recursively. + If neither X nor Y is a cons cell, they are compared by `eql', or + according to the specified test. The `:key' function, if + specified, is applied to the elements of both trees. *Note + Sequences::. + + +File: cl.info, Node: Substitution of Expressions, Next: Lists as Sets, Prev: List Functions, Up: Lists + +11.2 Substitution of Expressions +================================ + +These functions substitute elements throughout a tree of cons cells. +(*Note Sequence Functions::, for the `substitute' function, which works +on just the top-level elements of a list.) + + -- Function: subst new old tree &key :test :test-not :key + This function substitutes occurrences of OLD with NEW in TREE, a + tree of cons cells. It returns a substituted tree, which will be + a copy except that it may share storage with the argument TREE in + parts where no substitutions occurred. The original TREE is not + modified. This function recurses on, and compares against OLD, + both `car's and `cdr's of the component cons cells. If OLD is + itself a cons cell, then matching cells in the tree are + substituted as usual without recursively substituting in that + cell. Comparisons with OLD are done according to the specified + test (`eql' by default). The `:key' function is applied to the + elements of the tree but not to OLD. + + -- Function: nsubst new old tree &key :test :test-not :key + This function is like `subst', except that it works by destructive + modification (by `setcar' or `setcdr') rather than copying. + + The `subst-if', `subst-if-not', `nsubst-if', and `nsubst-if-not' +functions are defined similarly. + + -- Function: sublis alist tree &key :test :test-not :key + This function is like `subst', except that it takes an association + list ALIST of OLD-NEW pairs. Each element of the tree (after + applying the `:key' function, if any), is compared with the `car's + of ALIST; if it matches, it is replaced by the corresponding `cdr'. + + -- Function: nsublis alist tree &key :test :test-not :key + This is a destructive version of `sublis'. + + +File: cl.info, Node: Lists as Sets, Next: Association Lists, Prev: Substitution of Expressions, Up: Lists + +11.3 Lists as Sets +================== + +These functions perform operations on lists which represent sets of +elements. + + -- Function: member item list + This MacLisp-compatible function searches LIST for an element + which is `equal' to ITEM. The `member' function is built-in to + Emacs 19; this package defines it equivalently in Emacs 18. See + the following function for a Common-Lisp compatible version. + + -- Function: member* item list &key :test :test-not :key + This function searches LIST for an element matching ITEM. If a + match is found, it returns the cons cell whose `car' was the + matching element. Otherwise, it returns `nil'. Elements are + compared by `eql' by default; you can use the `:test', + `:test-not', and `:key' arguments to modify this behavior. *Note + Sequences::. + + Note that this function's name is suffixed by `*' to avoid the + incompatible `member' function defined in Emacs 19. (That + function uses `equal' for comparisons; it is equivalent to + `(member* ITEM LIST :test 'equal)'.) + + The `member-if' and `member-if-not' functions analogously search for +elements which satisfy a given predicate. + + -- Function: tailp sublist list + This function returns `t' if SUBLIST is a sublist of LIST, i.e., + if SUBLIST is `eql' to LIST or to any of its `cdr's. + + -- Function: adjoin item list &key :test :test-not :key + This function conses ITEM onto the front of LIST, like `(cons ITEM + LIST)', but only if ITEM is not already present on the list (as + determined by `member*'). If a `:key' argument is specified, it + is applied to ITEM as well as to the elements of LIST during the + search, on the reasoning that ITEM is "about" to become part of + the list. + + -- Function: union list1 list2 &key :test :test-not :key + This function combines two lists which represent sets of items, + returning a list that represents the union of those two sets. The + result list will contain all items which appear in LIST1 or LIST2, + and no others. If an item appears in both LIST1 and LIST2 it will + be copied only once. If an item is duplicated in LIST1 or LIST2, + it is undefined whether or not that duplication will survive in the + result list. The order of elements in the result list is also + undefined. + + -- Function: nunion list1 list2 &key :test :test-not :key + This is a destructive version of `union'; rather than copying, it + tries to reuse the storage of the argument lists if possible. + + -- Function: intersection list1 list2 &key :test :test-not :key + This function computes the intersection of the sets represented by + LIST1 and LIST2. It returns the list of items which appear in + both LIST1 and LIST2. + + -- Function: nintersection list1 list2 &key :test :test-not :key + This is a destructive version of `intersection'. It tries to + reuse storage of LIST1 rather than copying. It does _not_ reuse + the storage of LIST2. + + -- Function: set-difference list1 list2 &key :test :test-not :key + This function computes the "set difference" of LIST1 and LIST2, + i.e., the set of elements that appear in LIST1 but _not_ in LIST2. + + -- Function: nset-difference list1 list2 &key :test :test-not :key + This is a destructive `set-difference', which will try to reuse + LIST1 if possible. + + -- Function: set-exclusive-or list1 list2 &key :test :test-not :key + This function computes the "set exclusive or" of LIST1 and LIST2, + i.e., the set of elements that appear in exactly one of LIST1 and + LIST2. + + -- Function: nset-exclusive-or list1 list2 &key :test :test-not :key + This is a destructive `set-exclusive-or', which will try to reuse + LIST1 and LIST2 if possible. + + -- Function: subsetp list1 list2 &key :test :test-not :key + This function checks whether LIST1 represents a subset of LIST2, + i.e., whether every element of LIST1 also appears in LIST2. + + +File: cl.info, Node: Association Lists, Prev: Lists as Sets, Up: Lists + +11.4 Association Lists +====================== + +An "association list" is a list representing a mapping from one set of +values to another; any list whose elements are cons cells is an +association list. + + -- Function: assoc* item a-list &key :test :test-not :key + This function searches the association list A-LIST for an element + whose `car' matches (in the sense of `:test', `:test-not', and + `:key', or by comparison with `eql') a given ITEM. It returns the + matching element, if any, otherwise `nil'. It ignores elements of + A-LIST which are not cons cells. (This corresponds to the + behavior of `assq' and `assoc' in Emacs Lisp; Common Lisp's + `assoc' ignores `nil's but considers any other non-cons elements + of A-LIST to be an error.) + + -- Function: rassoc* item a-list &key :test :test-not :key + This function searches for an element whose `cdr' matches ITEM. + If A-LIST represents a mapping, this applies the inverse of the + mapping to ITEM. + + -- Function: rassoc item a-list + This function searches like `rassoc*' with a `:test' argument of + `equal'. It is analogous to Emacs Lisp's standard `assoc' + function, which derives from the MacLisp rather than the Common + Lisp tradition. + + The `assoc-if', `assoc-if-not', `rassoc-if', and `rassoc-if-not' +functions are defined similarly. + + Two simple functions for constructing association lists are: + + -- Function: acons key value alist + This is equivalent to `(cons (cons KEY VALUE) ALIST)'. + + -- Function: pairlis keys values &optional alist + This is equivalent to `(nconc (mapcar* 'cons KEYS VALUES) ALIST)'. + + +File: cl.info, Node: Hash Tables, Next: Structures, Prev: Lists, Up: Top + +12 Hash Tables +************** + +Hash tables are now implemented directly in the C code and documented in +*Note Hash Tables: (lispref)Hash Tables. + + +File: cl.info, Node: Structures, Next: Assertions, Prev: Hash Tables, Up: Top + +13 Structures +************* + +The Common Lisp "structure" mechanism provides a general way to define +data types similar to C's `struct' types. A structure is a Lisp object +containing some number of "slots", each of which can hold any Lisp data +object. Functions are provided for accessing and setting the slots, +creating or copying structure objects, and recognizing objects of a +particular structure type. + + In true Common Lisp, each structure type is a new type distinct from +all existing Lisp types. Since the underlying Emacs Lisp system +provides no way to create new distinct types, this package implements +structures as vectors (or lists upon request) with a special "tag" +symbol to identify them. + + -- Special Form: defstruct name slots... + The `defstruct' form defines a new structure type called NAME, + with the specified SLOTS. (The SLOTS may begin with a string + which documents the structure type.) In the simplest case, NAME + and each of the SLOTS are symbols. For example, + + (defstruct person name age sex) + + defines a struct type called `person' which contains three slots. + Given a `person' object P, you can access those slots by calling + `(person-name P)', `(person-age P)', and `(person-sex P)'. You + can also change these slots by using `setf' on any of these place + forms: + + (incf (person-age birthday-boy)) + + You can create a new `person' by calling `make-person', which + takes keyword arguments `:name', `:age', and `:sex' to specify the + initial values of these slots in the new object. (Omitting any of + these arguments leaves the corresponding slot "undefined," + according to the Common Lisp standard; in Emacs Lisp, such + uninitialized slots are filled with `nil'.) + + Given a `person', `(copy-person P)' makes a new object of the same + type whose slots are `eq' to those of P. + + Given any Lisp object X, `(person-p X)' returns true if X looks + like a `person', false otherwise. (Again, in Common Lisp this + predicate would be exact; in Emacs Lisp the best it can do is + verify that X is a vector of the correct length which starts with + the correct tag symbol.) + + Accessors like `person-name' normally check their arguments + (effectively using `person-p') and signal an error if the argument + is the wrong type. This check is affected by `(optimize (safety + ...))' declarations. Safety level 1, the default, uses a somewhat + optimized check that will detect all incorrect arguments, but may + use an uninformative error message (e.g., "expected a vector" + instead of "expected a `person'"). Safety level 0 omits all + checks except as provided by the underlying `aref' call; safety + levels 2 and 3 do rigorous checking that will always print a + descriptive error message for incorrect inputs. *Note + Declarations::. + + (setq dave (make-person :name "Dave" :sex 'male)) + => [cl-struct-person "Dave" nil male] + (setq other (copy-person dave)) + => [cl-struct-person "Dave" nil male] + (eq dave other) + => nil + (eq (person-name dave) (person-name other)) + => t + (person-p dave) + => t + (person-p [1 2 3 4]) + => nil + (person-p "Bogus") + => nil + (person-p '[cl-struct-person counterfeit person object]) + => t + + In general, NAME is either a name symbol or a list of a name + symbol followed by any number of "struct options"; each SLOT is + either a slot symbol or a list of the form `(SLOT-NAME + DEFAULT-VALUE SLOT-OPTIONS...)'. The DEFAULT-VALUE is a Lisp form + which is evaluated any time an instance of the structure type is + created without specifying that slot's value. + + Common Lisp defines several slot options, but the only one + implemented in this package is `:read-only'. A non-`nil' value + for this option means the slot should not be `setf'-able; the + slot's value is determined when the object is created and does not + change afterward. + + (defstruct person + (name nil :read-only t) + age + (sex 'unknown)) + + Any slot options other than `:read-only' are ignored. + + For obscure historical reasons, structure options take a different + form than slot options. A structure option is either a keyword + symbol, or a list beginning with a keyword symbol possibly followed + by arguments. (By contrast, slot options are key-value pairs not + enclosed in lists.) + + (defstruct (person (:constructor create-person) + (:type list) + :named) + name age sex) + + The following structure options are recognized. + + `:conc-name' + The argument is a symbol whose print name is used as the + prefix for the names of slot accessor functions. The default + is the name of the struct type followed by a hyphen. The + option `(:conc-name p-)' would change this prefix to `p-'. + Specifying `nil' as an argument means no prefix, so that the + slot names themselves are used to name the accessor functions. + + `:constructor' + In the simple case, this option takes one argument which is an + alternate name to use for the constructor function. The + default is `make-NAME', e.g., `make-person'. The above + example changes this to `create-person'. Specifying `nil' as + an argument means that no standard constructor should be + generated at all. + + In the full form of this option, the constructor name is + followed by an arbitrary argument list. *Note Program + Structure::, for a description of the format of Common Lisp + argument lists. All options, such as `&rest' and `&key', are + supported. The argument names should match the slot names; + each slot is initialized from the corresponding argument. + Slots whose names do not appear in the argument list are + initialized based on the DEFAULT-VALUE in their slot + descriptor. Also, `&optional' and `&key' arguments which + don't specify defaults take their defaults from the slot + descriptor. It is legal to include arguments which don't + correspond to slot names; these are useful if they are + referred to in the defaults for optional, keyword, or `&aux' + arguments which _do_ correspond to slots. + + You can specify any number of full-format `:constructor' + options on a structure. The default constructor is still + generated as well unless you disable it with a simple-format + `:constructor' option. + + (defstruct + (person + (:constructor nil) ; no default constructor + (:constructor new-person (name sex &optional (age 0))) + (:constructor new-hound (&key (name "Rover") + (dog-years 0) + &aux (age (* 7 dog-years)) + (sex 'canine)))) + name age sex) + + The first constructor here takes its arguments positionally + rather than by keyword. (In official Common Lisp + terminology, constructors that work By Order of Arguments + instead of by keyword are called "BOA constructors." No, I'm + not making this up.) For example, `(new-person "Jane" + 'female)' generates a person whose slots are `"Jane"', 0, and + `female', respectively. + + The second constructor takes two keyword arguments, `:name', + which initializes the `name' slot and defaults to `"Rover"', + and `:dog-years', which does not itself correspond to a slot + but which is used to initialize the `age' slot. The `sex' + slot is forced to the symbol `canine' with no syntax for + overriding it. + + `:copier' + The argument is an alternate name for the copier function for + this type. The default is `copy-NAME'. `nil' means not to + generate a copier function. (In this implementation, all + copier functions are simply synonyms for `copy-sequence'.) + + `:predicate' + The argument is an alternate name for the predicate which + recognizes objects of this type. The default is `NAME-p'. + `nil' means not to generate a predicate function. (If the + `:type' option is used without the `:named' option, no + predicate is ever generated.) + + In true Common Lisp, `typep' is always able to recognize a + structure object even if `:predicate' was used. In this + package, `typep' simply looks for a function called + `TYPENAME-p', so it will work for structure types only if + they used the default predicate name. + + `:include' + This option implements a very limited form of C++-style + inheritance. The argument is the name of another structure + type previously created with `defstruct'. The effect is to + cause the new structure type to inherit all of the included + structure's slots (plus, of course, any new slots described + by this struct's slot descriptors). The new structure is + considered a "specialization" of the included one. In fact, + the predicate and slot accessors for the included type will + also accept objects of the new type. + + If there are extra arguments to the `:include' option after + the included-structure name, these options are treated as + replacement slot descriptors for slots in the included + structure, possibly with modified default values. Borrowing + an example from Steele: + + (defstruct person name (age 0) sex) + => person + (defstruct (astronaut (:include person (age 45))) + helmet-size + (favorite-beverage 'tang)) + => astronaut + + (setq joe (make-person :name "Joe")) + => [cl-struct-person "Joe" 0 nil] + (setq buzz (make-astronaut :name "Buzz")) + => [cl-struct-astronaut "Buzz" 45 nil nil tang] + + (list (person-p joe) (person-p buzz)) + => (t t) + (list (astronaut-p joe) (astronaut-p buzz)) + => (nil t) + + (person-name buzz) + => "Buzz" + (astronaut-name joe) + => error: "astronaut-name accessing a non-astronaut" + + Thus, if `astronaut' is a specialization of `person', then + every `astronaut' is also a `person' (but not the other way + around). Every `astronaut' includes all the slots of a + `person', plus extra slots that are specific to astronauts. + Operations that work on people (like `person-name') work on + astronauts just like other people. + + `:print-function' + In full Common Lisp, this option allows you to specify a + function which is called to print an instance of the + structure type. The Emacs Lisp system offers no hooks into + the Lisp printer which would allow for such a feature, so + this package simply ignores `:print-function'. + + `:type' + The argument should be one of the symbols `vector' or `list'. + This tells which underlying Lisp data type should be used to + implement the new structure type. Vectors are used by + default, but `(:type list)' will cause structure objects to + be stored as lists instead. + + The vector representation for structure objects has the + advantage that all structure slots can be accessed quickly, + although creating vectors is a bit slower in Emacs Lisp. + Lists are easier to create, but take a relatively long time + accessing the later slots. + + `:named' + This option, which takes no arguments, causes a + characteristic "tag" symbol to be stored at the front of the + structure object. Using `:type' without also using `:named' + will result in a structure type stored as plain vectors or + lists with no identifying features. + + The default, if you don't specify `:type' explicitly, is to + use named vectors. Therefore, `:named' is only useful in + conjunction with `:type'. + + (defstruct (person1) name age sex) + (defstruct (person2 (:type list) :named) name age sex) + (defstruct (person3 (:type list)) name age sex) + + (setq p1 (make-person1)) + => [cl-struct-person1 nil nil nil] + (setq p2 (make-person2)) + => (person2 nil nil nil) + (setq p3 (make-person3)) + => (nil nil nil) + + (person1-p p1) + => t + (person2-p p2) + => t + (person3-p p3) + => error: function person3-p undefined + + Since unnamed structures don't have tags, `defstruct' is not + able to make a useful predicate for recognizing them. Also, + accessors like `person3-name' will be generated but they will + not be able to do any type checking. The `person3-name' + function, for example, will simply be a synonym for `car' in + this case. By contrast, `person2-name' is able to verify + that its argument is indeed a `person2' object before + proceeding. + + `:initial-offset' + The argument must be a nonnegative integer. It specifies a + number of slots to be left "empty" at the front of the + structure. If the structure is named, the tag appears at the + specified position in the list or vector; otherwise, the first + slot appears at that position. Earlier positions are filled + with `nil' by the constructors and ignored otherwise. If the + type `:include's another type, then `:initial-offset' + specifies a number of slots to be skipped between the last + slot of the included type and the first new slot. + + Except as noted, the `defstruct' facility of this package is +entirely compatible with that of Common Lisp. + + +File: cl.info, Node: Assertions, Next: Efficiency Concerns, Prev: Structures, Up: Top + +14 Assertions and Errors +************************ + +This section describes two macros that test "assertions", i.e., +conditions which must be true if the program is operating correctly. +Assertions never add to the behavior of a Lisp program; they simply +make "sanity checks" to make sure everything is as it should be. + + If the optimization property `speed' has been set to 3, and `safety' +is less than 3, then the byte-compiler will optimize away the following +assertions. Because assertions might be optimized away, it is a bad +idea for them to include side-effects. + + -- Special Form: assert test-form [show-args string args...] + This form verifies that TEST-FORM is true (i.e., evaluates to a + non-`nil' value). If so, it returns `nil'. If the test is not + satisfied, `assert' signals an error. + + A default error message will be supplied which includes TEST-FORM. + You can specify a different error message by including a STRING + argument plus optional extra arguments. Those arguments are simply + passed to `error' to signal the error. + + If the optional second argument SHOW-ARGS is `t' instead of `nil', + then the error message (with or without STRING) will also include + all non-constant arguments of the top-level FORM. For example: + + (assert (> x 10) t "x is too small: %d") + + This usage of SHOW-ARGS is a change to Common Lisp. In true + Common Lisp, the second argument gives a list of PLACES which can + be `setf''d by the user before continuing from the error. + + -- Special Form: check-type place type &optional string + This form verifies that PLACE evaluates to a value of type TYPE. + If so, it returns `nil'. If not, `check-type' signals a + continuable `wrong-type-argument' error. The default error + message lists the erroneous value along with TYPE and PLACE + themselves. If STRING is specified, it is included in the error + message in place of TYPE. For example: + + (check-type x (integer 1 *) "a positive integer") + + *Note Type Predicates::, for a description of the type specifiers + that may be used for TYPE. + + Note that as in Common Lisp, the first argument to `check-type' + should be a PLACE suitable for use by `setf', because `check-type' + signals a continuable error that allows the user to modify PLACE, + most simply by returning a value from the debugger. + + The following error-related macro is also defined: + + -- Special Form: ignore-errors forms... + This executes FORMS exactly like a `progn', except that errors are + ignored during the FORMS. More precisely, if an error is + signalled then `ignore-errors' immediately aborts execution of the + FORMS and returns `nil'. If the FORMS complete successfully, + `ignore-errors' returns the result of the last FORM. + + +File: cl.info, Node: Efficiency Concerns, Next: Common Lisp Compatibility, Prev: Assertions, Up: Top + +Appendix A Efficiency Concerns +****************************** + +A.1 Macros +========== + +Many of the advanced features of this package, such as `defun*', +`loop', and `setf', are implemented as Lisp macros. In byte-compiled +code, these complex notations will be expanded into equivalent Lisp +code which is simple and efficient. For example, the forms + + (incf i n) + (push x (car p)) + +are expanded at compile-time to the Lisp forms + + (setq i (+ i n)) + (setcar p (cons x (car p))) + +which are the most efficient ways of doing these respective operations +in Lisp. Thus, there is no performance penalty for using the more +readable `incf' and `push' forms in your compiled code. + + _Interpreted_ code, on the other hand, must expand these macros +every time they are executed. For this reason it is strongly +recommended that code making heavy use of macros be compiled. (The +features labelled "Special Form" instead of "Function" in this manual +are macros.) A loop using `incf' a hundred times will execute +considerably faster if compiled, and will also garbage-collect less +because the macro expansion will not have to be generated, used, and +thrown away a hundred times. + + You can find out how a macro expands by using the `cl-prettyexpand' +function. + + -- Function: cl-prettyexpand form &optional full + This function takes a single Lisp form as an argument and inserts + a nicely formatted copy of it in the current buffer (which must be + in Lisp mode so that indentation works properly). It also expands + all Lisp macros which appear in the form. The easiest way to use + this function is to go to the `*scratch*' buffer and type, say, + + (cl-prettyexpand '(loop for x below 10 collect x)) + + and type `C-x C-e' immediately after the closing parenthesis; the + expansion + + (block nil + (let* ((x 0) + (G1004 nil)) + (while (< x 10) + (setq G1004 (cons x G1004)) + (setq x (+ x 1))) + (nreverse G1004))) + + will be inserted into the buffer. (The `block' macro is expanded + differently in the interpreter and compiler, so `cl-prettyexpand' + just leaves it alone. The temporary variable `G1004' was created + by `gensym'.) + + If the optional argument FULL is true, then _all_ macros are + expanded, including `block', `eval-when', and compiler macros. + Expansion is done as if FORM were a top-level form in a file being + compiled. For example, + + (cl-prettyexpand '(pushnew 'x list)) + -| (setq list (adjoin 'x list)) + (cl-prettyexpand '(pushnew 'x list) t) + -| (setq list (if (memq 'x list) list (cons 'x list))) + (cl-prettyexpand '(caddr (member* 'a list)) t) + -| (car (cdr (cdr (memq 'a list)))) + + Note that `adjoin', `caddr', and `member*' all have built-in + compiler macros to optimize them in common cases. + + +A.2 Error Checking +================== + +Common Lisp compliance has in general not been sacrificed for the sake +of efficiency. A few exceptions have been made for cases where +substantial gains were possible at the expense of marginal +incompatibility. One example is the use of `memq' (which is treated +very efficiently by the byte-compiler) to scan for keyword arguments; +this can become confused in rare cases when keyword symbols are used as +both keywords and data values at once. This is extremely unlikely to +occur in practical code, and the use of `memq' allows functions with +keyword arguments to be nearly as fast as functions that use +`&optional' arguments. + + The Common Lisp standard (as embodied in Steele's book) uses the +phrase "it is an error if" to indicate a situation which is not +supposed to arise in complying programs; implementations are strongly +encouraged but not required to signal an error in these situations. +This package sometimes omits such error checking in the interest of +compactness and efficiency. For example, `do' variable specifiers are +supposed to be lists of one, two, or three forms; extra forms are +ignored by this package rather than signalling a syntax error. The +`endp' function is simply a synonym for `null' in this package. +Functions taking keyword arguments will accept an odd number of +arguments, treating the trailing keyword as if it were followed by the +value `nil'. + + Argument lists (as processed by `defun*' and friends) _are_ checked +rigorously except for the minor point just mentioned; in particular, +keyword arguments are checked for validity, and `&allow-other-keys' and +`:allow-other-keys' are fully implemented. Keyword validity checking +is slightly time consuming (though not too bad in byte-compiled code); +you can use `&allow-other-keys' to omit this check. Functions defined +in this package such as `find' and `member*' do check their keyword +arguments for validity. + + +A.3 Optimizing Compiler +======================= + +The byte-compiler that comes with Emacs 18 normally fails to expand +macros that appear in top-level positions in the file (i.e., outside of +`defun's or other enclosing forms). This would have disastrous +consequences to programs that used such top-level macros as `defun*', +`eval-when', and `defstruct'. To work around this problem, the "CL" +package patches the Emacs 18 compiler to expand top-level macros. This +patch will apply to your own macros, too, if they are used in a +top-level context. The patch will not harm versions of the Emacs 18 +compiler which have already had a similar patch applied, nor will it +affect the optimizing Emacs 19 byte-compiler written by Jamie Zawinski +and Hallvard Furuseth. The patch is applied to the byte compiler's +code in Emacs' memory, _not_ to the `bytecomp.elc' file stored on disk. + + The Emacs 19 compiler (for Emacs 18) is available from various Emacs +Lisp archive sites such as `archive.cis.ohio-state.edu'. Its use is +highly recommended; many of the Common Lisp macros emit code which can +be improved by optimization. In particular, `block's (whether explicit +or implicit in constructs like `defun*' and `loop') carry a fair +run-time penalty; the optimizing compiler removes `block's which are +not actually referenced by `return' or `return-from' inside the block. + + +File: cl.info, Node: Common Lisp Compatibility, Next: Old CL Compatibility, Prev: Efficiency Concerns, Up: Top + +Appendix B Common Lisp Compatibility +************************************ + +Following is a list of all known incompatibilities between this package +and Common Lisp as documented in Steele (2nd edition). + + Certain function names, such as `member', `assoc', and `floor', were +already taken by (incompatible) Emacs Lisp functions; this package +appends `*' to the names of its Common Lisp versions of these functions. + + The word `defun*' is required instead of `defun' in order to use +extended Common Lisp argument lists in a function. Likewise, +`defmacro*' and `function*' are versions of those forms which +understand full-featured argument lists. The `&whole' keyword does not +work in `defmacro' argument lists (except inside recursive argument +lists). + + In order to allow an efficient implementation, keyword arguments use +a slightly cheesy parser which may be confused if a keyword symbol is +passed as the _value_ of another keyword argument. (Specifically, +`(memq :KEYWORD REST-OF-ARGUMENTS)' is used to scan for `:KEYWORD' +among the supplied keyword arguments.) + + The `eql' and `equal' predicates do not distinguish between IEEE +floating-point plus and minus zero. The `equalp' predicate has several +differences with Common Lisp; *note Predicates::. + + The `setf' mechanism is entirely compatible, except that +setf-methods return a list of five values rather than five values +directly. Also, the new "`setf' function" concept (typified by `(defun +(setf foo) ...)') is not implemented. + + The `do-all-symbols' form is the same as `do-symbols' with no +OBARRAY argument. In Common Lisp, this form would iterate over all +symbols in all packages. Since Emacs obarrays are not a first-class +package mechanism, there is no way for `do-all-symbols' to locate any +but the default obarray. + + The `loop' macro is complete except that `loop-finish' and type +specifiers are unimplemented. + + The multiple-value return facility treats lists as multiple values, +since Emacs Lisp cannot support multiple return values directly. The +macros will be compatible with Common Lisp if `values' or `values-list' +is always used to return to a `multiple-value-bind' or other +multiple-value receiver; if `values' is used without +`multiple-value-...' or vice-versa the effect will be different from +Common Lisp. + + Many Common Lisp declarations are ignored, and others match the +Common Lisp standard in concept but not in detail. For example, local +`special' declarations, which are purely advisory in Emacs Lisp, do not +rigorously obey the scoping rules set down in Steele's book. + + The variable `*gensym-counter*' starts out with a pseudo-random +value rather than with zero. This is to cope with the fact that +generated symbols become interned when they are written to and loaded +back from a file. + + The `defstruct' facility is compatible, except that structures are +of type `:type vector :named' by default rather than some special, +distinct type. Also, the `:type' slot option is ignored. + + The second argument of `check-type' is treated differently. + + +File: cl.info, Node: Old CL Compatibility, Next: Porting Common Lisp, Prev: Common Lisp Compatibility, Up: Top + +Appendix C Old CL Compatibility +******************************* + +Following is a list of all known incompatibilities between this package +and the older Quiroz `cl.el' package. + + This package's emulation of multiple return values in functions is +incompatible with that of the older package. That package attempted to +come as close as possible to true Common Lisp multiple return values; +unfortunately, it could not be 100% reliable and so was prone to +occasional surprises if used freely. This package uses a simpler +method, namely replacing multiple values with lists of values, which is +more predictable though more noticeably different from Common Lisp. + + The `defkeyword' form and `keywordp' function are not implemented in +this package. + + The `member', `floor', `ceiling', `truncate', `round', `mod', and +`rem' functions are suffixed by `*' in this package to avoid collision +with existing functions in Emacs 18 or Emacs 19. The older package +simply redefined these functions, overwriting the built-in meanings and +causing serious portability problems with Emacs 19. (Some more recent +versions of the Quiroz package changed the names to `cl-member', etc.; +this package defines the latter names as aliases for `member*', etc.) + + Certain functions in the old package which were buggy or inconsistent +with the Common Lisp standard are incompatible with the conforming +versions in this package. For example, `eql' and `member' were +synonyms for `eq' and `memq' in that package, `setf' failed to preserve +correct order of evaluation of its arguments, etc. + + Finally, unlike the older package, this package is careful to prefix +all of its internal names with `cl-'. Except for a few functions which +are explicitly defined as additional features (such as `floatp-safe' +and `letf'), this package does not export any non-`cl-' symbols which +are not also part of Common Lisp. + + +C.1 The `cl-compat' package +=========================== + +The "CL" package includes emulations of some features of the old +`cl.el', in the form of a compatibility package `cl-compat'. To use +it, put `(require 'cl-compat)' in your program. + + The old package defined a number of internal routines without `cl-' +prefixes or other annotations. Call to these routines may have crept +into existing Lisp code. `cl-compat' provides emulations of the +following internal routines: `pair-with-newsyms', `zip-lists', +`unzip-lists', `reassemble-arglists', `duplicate-symbols-p', +`safe-idiv'. + + Some `setf' forms translated into calls to internal functions that +user code might call directly. The functions `setnth', `setnthcdr', +and `setelt' fall in this category; they are defined by `cl-compat', +but the best fix is to change to use `setf' properly. + + The `cl-compat' file defines the keyword functions `keywordp', +`keyword-of', and `defkeyword', which are not defined by the new "CL" +package because the use of keywords as data is discouraged. + + The `build-klist' mechanism for parsing keyword arguments is +emulated by `cl-compat'; the `with-keyword-args' macro is not, however, +and in any case it's best to change to use the more natural keyword +argument processing offered by `defun*'. + + Multiple return values are treated differently by the two Common +Lisp packages. The old package's method was more compatible with true +Common Lisp, though it used heuristics that caused it to report +spurious multiple return values in certain cases. The `cl-compat' +package defines a set of multiple-value macros that are compatible with +the old CL package; again, they are heuristic in nature, but they are +guaranteed to work in any case where the old package's macros worked. +To avoid name collision with the "official" multiple-value facilities, +the ones in `cl-compat' have capitalized names: `Values', +`Values-list', `Multiple-value-bind', etc. + + The functions `cl-floor', `cl-ceiling', `cl-truncate', and +`cl-round' are defined by `cl-compat' to use the old-style +multiple-value mechanism, just as they did in the old package. The +newer `floor*' and friends return their two results in a list rather +than as multiple values. Note that older versions of the old package +used the unadorned names `floor', `ceiling', etc.; `cl-compat' cannot +use these names because they conflict with Emacs 19 built-ins. + + +File: cl.info, Node: Porting Common Lisp, Next: Function Index, Prev: Old CL Compatibility, Up: Top + +Appendix D Porting Common Lisp +****************************** + +This package is meant to be used as an extension to Emacs Lisp, not as +an Emacs implementation of true Common Lisp. Some of the remaining +differences between Emacs Lisp and Common Lisp make it difficult to +port large Common Lisp applications to Emacs. For one, some of the +features in this package are not fully compliant with ANSI or Steele; +*note Common Lisp Compatibility::. But there are also quite a few +features that this package does not provide at all. Here are some +major omissions that you will want watch out for when bringing Common +Lisp code into Emacs. + + * Case-insensitivity. Symbols in Common Lisp are case-insensitive + by default. Some programs refer to a function or variable as + `foo' in one place and `Foo' or `FOO' in another. Emacs Lisp will + treat these as three distinct symbols. + + Some Common Lisp code is written in all upper-case. While Emacs + is happy to let the program's own functions and variables use this + convention, calls to Lisp builtins like `if' and `defun' will have + to be changed to lower-case. + + * Lexical scoping. In Common Lisp, function arguments and `let' + bindings apply only to references physically within their bodies + (or within macro expansions in their bodies). Emacs Lisp, by + contrast, uses "dynamic scoping" wherein a binding to a variable + is visible even inside functions called from the body. + + Variables in Common Lisp can be made dynamically scoped by + declaring them `special' or using `defvar'. In Emacs Lisp it is + as if all variables were declared `special'. + + Often you can use code that was written for lexical scoping even + in a dynamically scoped Lisp, but not always. Here is an example + of a Common Lisp code fragment that would fail in Emacs Lisp: + + (defun map-odd-elements (func list) + (loop for x in list + for flag = t then (not flag) + collect (if flag x (funcall func x)))) + + (defun add-odd-elements (list x) + (map-odd-elements (function (lambda (a) (+ a x))) list)) + + In Common Lisp, the two functions' usages of `x' are completely + independent. In Emacs Lisp, the binding to `x' made by + `add-odd-elements' will have been hidden by the binding in + `map-odd-elements' by the time the `(+ a x)' function is called. + + (This package avoids such problems in its own mapping functions by + using names like `cl-x' instead of `x' internally; as long as you + don't use the `cl-' prefix for your own variables no collision can + occur.) + + *Note Lexical Bindings::, for a description of the `lexical-let' + form which establishes a Common Lisp-style lexical binding, and + some examples of how it differs from Emacs' regular `let'. + + * Common Lisp allows the shorthand `#'x' to stand for `(function + x)', just as `'x' stands for `(quote x)'. In Common Lisp, one + traditionally uses `#'' notation when referring to the name of a + function. In Emacs Lisp, it works just as well to use a regular + quote: + + (loop for x in y by #'cddr collect (mapcar #'plusp x)) ; Common Lisp + (loop for x in y by 'cddr collect (mapcar 'plusp x)) ; Emacs Lisp + + When `#'' introduces a `lambda' form, it is best to write out + `(function ...)' longhand in Emacs Lisp. You can use a regular + quote, but then the byte-compiler won't know that the `lambda' + expression is code that can be compiled. + + (mapcar #'(lambda (x) (* x 2)) list) ; Common Lisp + (mapcar (function (lambda (x) (* x 2))) list) ; Emacs Lisp + + XEmacs supports `#'' notation starting with version 19.8. + + * Reader macros. Common Lisp includes a second type of macro that + works at the level of individual characters. For example, Common + Lisp implements the quote notation by a reader macro called `'', + whereas Emacs Lisp's parser just treats quote as a special case. + Some Lisp packages use reader macros to create special syntaxes + for themselves, which the Emacs parser is incapable of reading. + + * Other syntactic features. Common Lisp provides a number of + notations beginning with `#' that the Emacs Lisp parser won't + understand. For example, `#| ... |#' is an alternate comment + notation, and `#+lucid (foo)' tells the parser to ignore the + `(foo)' except in Lucid Common Lisp. + + The number prefixes `#b', `#o', and `#x', however, are supported + by the Emacs Lisp parser to represent numbers in binary, octal, + and hexadecimal notation (or radix), just like in Common Lisp. + + * Packages. In Common Lisp, symbols are divided into "packages". + Symbols that are Lisp built-ins are typically stored in one + package; symbols that are vendor extensions are put in another, + and each application program would have a package for its own + symbols. Certain symbols are "exported" by a package and others + are internal; certain packages "use" or import the exported symbols + of other packages. To access symbols that would not normally be + visible due to this importing and exporting, Common Lisp provides + a syntax like `package:symbol' or `package::symbol'. + + Emacs Lisp has a single namespace for all interned symbols, and + then uses a naming convention of putting a prefix like `cl-' in + front of the name. Some Emacs packages adopt the Common Lisp-like + convention of using `cl:' or `cl::' as the prefix. However, the + Emacs parser does not understand colons and just treats them as + part of the symbol name. Thus, while `mapcar' and `lisp:mapcar' + may refer to the same symbol in Common Lisp, they are totally + distinct in Emacs Lisp. Common Lisp programs which refer to a + symbol by the full name sometimes and the short name other times + will not port cleanly to Emacs. + + Emacs Lisp does have a concept of "obarrays," which are + package-like collections of symbols, but this feature is not + strong enough to be used as a true package mechanism. + + * Keywords. The notation `:test-not' in Common Lisp really is a + shorthand for `keyword:test-not'; keywords are just symbols in a + built-in `keyword' package with the special property that all its + symbols are automatically self-evaluating. Common Lisp programs + often use keywords liberally to avoid having to use quotes. + + In Emacs Lisp a keyword is just a symbol whose name begins with a + colon; since the Emacs parser does not treat them specially, they + have to be explicitly made self-evaluating by a statement like + `(setq :test-not ':test-not)'. This package arranges to execute + such a statement whenever `defun*' or some other form sees a + keyword being used as an argument. Common Lisp code that assumes + that a symbol `:mumble' will be self-evaluating even though it was + never introduced by a `defun*' will have to be fixed. + + * The `format' function is quite different between Common Lisp and + Emacs Lisp. It takes an additional "destination" argument before + the format string. A destination of `nil' means to format to a + string as in Emacs Lisp; a destination of `t' means to write to + the terminal (similar to `message' in Emacs). Also, format + control strings are utterly different; `~' is used instead of `%' + to introduce format codes, and the set of available codes is much + richer. There are no notations like `\n' for string literals; + instead, `format' is used with the "newline" format code, `~%'. + More advanced formatting codes provide such features as paragraph + filling, case conversion, and even loops and conditionals. + + While it would have been possible to implement most of Common Lisp + `format' in this package (under the name `format*', of course), it + was not deemed worthwhile. It would have required a huge amount + of code to implement even a decent subset of `format*', yet the + functionality it would provide over Emacs Lisp's `format' would + rarely be useful. + + * Vector constants use square brackets in Emacs Lisp, but `#(a b c)' + notation in Common Lisp. To further complicate matters, Emacs 19 + introduces its own `#(' notation for something entirely + different--strings with properties. + + * Characters are distinct from integers in Common Lisp. The + notation for character constants is also different: `#\A' instead + of `?A'. Also, `string=' and `string-equal' are synonyms in Emacs + Lisp whereas the latter is case-insensitive in Common Lisp. + + * Data types. Some Common Lisp data types do not exist in Emacs + Lisp. Rational numbers and complex numbers are not present, nor + are large integers (all integers are "fixnums"). All arrays are + one-dimensional. There are no readtables or pathnames; streams + are a set of existing data types rather than a new data type of + their own. Hash tables, random-states, structures, and packages + (obarrays) are built from Lisp vectors or lists rather than being + distinct types. + + * The Common Lisp Object System (CLOS) is not implemented, nor is + the Common Lisp Condition System. + + * Common Lisp features that are completely redundant with Emacs Lisp + features of a different name generally have not been implemented. + For example, Common Lisp writes `defconstant' where Emacs Lisp + uses `defconst'. Similarly, `make-list' takes its arguments in + different ways in the two Lisps but does exactly the same thing, + so this package has not bothered to implement a Common Lisp-style + `make-list'. + + * A few more notable Common Lisp features not included in this + package: `compiler-let', `tagbody', `prog', `ldb/dpb', + `parse-integer', `cerror'. + + * Recursion. While recursion works in Emacs Lisp just like it does + in Common Lisp, various details of the Emacs Lisp system and + compiler make recursion much less efficient than it is in most + Lisps. Some schools of thought prefer to use recursion in Lisp + over other techniques; they would sum a list of numbers using + something like + + (defun sum-list (list) + (if list + (+ (car list) (sum-list (cdr list))) + 0)) + + where a more iteratively-minded programmer might write one of + these forms: + + (let ((total 0)) (dolist (x my-list) (incf total x)) total) + (loop for x in my-list sum x) + + While this would be mainly a stylistic choice in most Common Lisps, + in Emacs Lisp you should be aware that the iterative forms are + much faster than recursion. Also, Lisp programmers will want to + note that the current Emacs Lisp compiler does not optimize tail + recursion. + + +File: cl.info, Node: Function Index, Next: Variable Index, Prev: Porting Common Lisp, Up: Top + +Function Index +************** + +[index] +* Menu: + +* abs: Numerical Functions. (line 9) +* acons: Association Lists. (line 37) +* adjoin: Lists as Sets. (line 36) +* assert: Assertions. (line 17) +* assoc*: Association Lists. (line 11) +* assoc-if: Association Lists. (line 31) +* assoc-if-not: Association Lists. (line 31) +* block: Blocks and Exits. (line 14) +* butlast: List Functions. (line 45) +* caddr: List Functions. (line 10) +* callf: Modify Macros. (line 146) +* callf2: Modify Macros. (line 161) +* case: Conditionals. (line 30) +* ceiling*: Numerical Functions. (line 61) +* check-type: Assertions. (line 37) +* cl-float-limits: Implementation Parameters. + (line 23) +* cl-prettyexpand: Efficiency Concerns. (line 39) +* coerce: Type Predicates. (line 66) +* compiler-macroexpand: Macros. (line 60) +* concatenate: Sequence Functions. (line 28) +* copy-list: List Functions. (line 75) +* copy-tree: List Functions. (line 79) +* count: Searching Sequences. (line 27) +* count-if: Searching Sequences. (line 30) +* count-if-not: Searching Sequences. (line 30) +* decf: Modify Macros. (line 46) +* declaim: Declarations. (line 27) +* declare: Declarations. (line 37) +* defalias: Function Aliases. (line 10) +* define-compiler-macro: Macros. (line 28) +* define-modify-macro: Customizing Setf. (line 11) +* define-setf-method: Customizing Setf. (line 99) +* defmacro*: Argument Lists. (line 35) +* defsetf: Customizing Setf. (line 41) +* defstruct: Structures. (line 20) +* defsubst*: Argument Lists. (line 24) +* deftype: Type Predicates. (line 77) +* defun*: Argument Lists. (line 18) +* delete: Sequence Functions. (line 81) +* delete*: Sequence Functions. (line 68) +* delete-duplicates: Sequence Functions. (line 107) +* delete-if: Sequence Functions. (line 77) +* delete-if-not: Sequence Functions. (line 77) +* destructuring-bind: Macros. (line 15) +* do: Iteration. (line 34) +* do*: Iteration. (line 73) +* do-all-symbols: Iteration. (line 115) +* do-symbols: Iteration. (line 106) +* dolist: Iteration. (line 89) +* dotimes: Iteration. (line 97) +* ecase: Conditionals. (line 58) +* endp: List Functions. (line 25) +* eql: Equality Predicates. (line 9) +* equalp: Equality Predicates. (line 40) +* etypecase: Conditionals. (line 79) +* eval-when: Time of Evaluation. (line 16) +* eval-when-compile: Time of Evaluation. (line 87) +* evenp: Predicates on Numbers. + (line 22) +* every: Mapping over Sequences. + (line 71) +* expt: Numerical Functions. (line 15) +* fill: Sequence Functions. (line 35) +* find: Searching Sequences. (line 11) +* find-if: Searching Sequences. (line 30) +* find-if-not: Searching Sequences. (line 30) +* first: List Functions. (line 17) +* flet: Function Bindings. (line 9) +* floatp-safe: Predicates on Numbers. + (line 26) +* floor*: Numerical Functions. (line 36) +* function*: Argument Lists. (line 44) +* gcd: Numerical Functions. (line 21) +* gensym: Creating Symbols. (line 10) +* gentemp: Creating Symbols. (line 34) +* get-setf-method: Customizing Setf. (line 138) +* getf: Property Lists. (line 12) +* ignore-errors: Assertions. (line 57) +* incf: Modify Macros. (line 18) +* intersection: Lists as Sets. (line 58) +* isqrt: Numerical Functions. (line 31) +* labels: Function Bindings. (line 45) +* last: List Functions. (line 37) +* lcm: Numerical Functions. (line 26) +* ldiff: List Functions. (line 67) +* letf: Modify Macros. (line 97) +* letf*: Modify Macros. (line 142) +* lexical-let: Lexical Bindings. (line 10) +* lexical-let*: Lexical Bindings. (line 98) +* list*: List Functions. (line 57) +* list-length: List Functions. (line 30) +* load-time-value: Time of Evaluation. (line 96) +* locally: Declarations. (line 45) +* loop <1>: Loop Basics. (line 16) +* loop: Iteration. (line 10) +* macrolet: Macro Bindings. (line 9) +* make-random-state: Random Numbers. (line 29) +* map: Mapping over Sequences. + (line 27) +* mapc: Mapping over Sequences. + (line 43) +* mapcan: Mapping over Sequences. + (line 53) +* mapcar*: Mapping over Sequences. + (line 11) +* mapcon: Mapping over Sequences. + (line 58) +* mapl: Mapping over Sequences. + (line 49) +* maplist: Mapping over Sequences. + (line 35) +* member: Lists as Sets. (line 10) +* member*: Lists as Sets. (line 16) +* member-if: Lists as Sets. (line 28) +* member-if-not: Lists as Sets. (line 28) +* merge: Sorting Sequences. (line 40) +* minusp: Predicates on Numbers. + (line 14) +* mismatch: Searching Sequences. (line 35) +* mod*: Numerical Functions. (line 81) +* multiple-value-bind: Multiple Values. (line 18) +* multiple-value-setq: Multiple Values. (line 25) +* nbutlast: List Functions. (line 52) +* nintersection: Lists as Sets. (line 63) +* notany: Mapping over Sequences. + (line 76) +* notevery: Mapping over Sequences. + (line 82) +* nset-difference: Lists as Sets. (line 72) +* nset-exclusive-or: Lists as Sets. (line 81) +* nsublis: Substitution of Expressions. + (line 37) +* nsubst: Substitution of Expressions. + (line 24) +* nsubst-if: Substitution of Expressions. + (line 27) +* nsubst-if-not: Substitution of Expressions. + (line 27) +* nsubstitute: Sequence Functions. (line 119) +* nsubstitute-if: Sequence Functions. (line 123) +* nsubstitute-if-not: Sequence Functions. (line 123) +* nunion: Lists as Sets. (line 54) +* oddp: Predicates on Numbers. + (line 18) +* pairlis: Association Lists. (line 40) +* plusp: Predicates on Numbers. + (line 10) +* pop: Modify Macros. (line 50) +* position: Searching Sequences. (line 20) +* position-if: Searching Sequences. (line 30) +* position-if-not: Searching Sequences. (line 30) +* proclaim: Declarations. (line 22) +* progv: Dynamic Bindings. (line 11) +* psetf: Modify Macros. (line 11) +* psetq: Assignment. (line 10) +* push: Modify Macros. (line 56) +* pushnew: Modify Macros. (line 61) +* random*: Random Numbers. (line 12) +* random-state-p: Random Numbers. (line 52) +* rassoc: Association Lists. (line 26) +* rassoc*: Association Lists. (line 21) +* rassoc-if: Association Lists. (line 31) +* rassoc-if-not: Association Lists. (line 31) +* reduce: Mapping over Sequences. + (line 89) +* rem*: Numerical Functions. (line 85) +* remf: Property Lists. (line 43) +* remove: Sequence Functions. (line 86) +* remove*: Sequence Functions. (line 52) +* remove-duplicates: Sequence Functions. (line 97) +* remove-if: Sequence Functions. (line 77) +* remove-if-not: Sequence Functions. (line 77) +* remq: Sequence Functions. (line 91) +* replace: Sequence Functions. (line 39) +* rest: List Functions. (line 22) +* return: Blocks and Exits. (line 58) +* return-from: Blocks and Exits. (line 52) +* rotatef: Modify Macros. (line 82) +* round*: Numerical Functions. (line 74) +* search: Searching Sequences. (line 54) +* set-difference: Lists as Sets. (line 68) +* set-exclusive-or: Lists as Sets. (line 76) +* setf: Basic Setf. (line 10) +* shiftf: Modify Macros. (line 67) +* some: Mapping over Sequences. + (line 62) +* sort*: Sorting Sequences. (line 7) +* stable-sort: Sorting Sequences. (line 30) +* sublis: Substitution of Expressions. + (line 31) +* subseq: Sequence Functions. (line 10) +* subsetp: Lists as Sets. (line 85) +* subst: Substitution of Expressions. + (line 11) +* subst-if: Substitution of Expressions. + (line 27) +* subst-if-not: Substitution of Expressions. + (line 27) +* substitute: Sequence Functions. (line 112) +* substitute-if: Sequence Functions. (line 123) +* substitute-if-not: Sequence Functions. (line 123) +* symbol-macrolet: Macro Bindings. (line 21) +* tailp: Lists as Sets. (line 32) +* the: Declarations. (line 48) +* tree-equal: List Functions. (line 88) +* truncate*: Numerical Functions. (line 67) +* typecase: Conditionals. (line 63) +* typep: Type Predicates. (line 9) +* union: Lists as Sets. (line 44) +* unless: Conditionals. (line 20) +* when: Conditionals. (line 10) + + +File: cl.info, Node: Variable Index, Prev: Function Index, Up: Top + +Variable Index +************** + +[index] +* Menu: + +* *gensym-counter*: Creating Symbols. (line 21) +* *random-state*: Random Numbers. (line 21) +* float-epsilon: Implementation Parameters. + (line 73) +* float-negative-epsilon: Implementation Parameters. + (line 79) +* least-negative-float: Implementation Parameters. + (line 65) +* least-negative-normalized-float: Implementation Parameters. + (line 69) +* least-positive-float: Implementation Parameters. + (line 52) +* least-positive-normalized-float: Implementation Parameters. + (line 57) +* most-negative-fixnum: Implementation Parameters. + (line 13) +* most-negative-float: Implementation Parameters. + (line 48) +* most-positive-fixnum: Implementation Parameters. + (line 9) +* most-positive-float: Implementation Parameters. + (line 42) + + + +Tag Table: +Node: Top1164 +Node: Overview2720 +Node: Usage5003 +Node: Organization5661 +Node: Installation7492 +Node: Naming Conventions8653 +Node: Program Structure10788 +Node: Argument Lists11260 +Node: Time of Evaluation21050 +Node: Function Aliases27041 +Node: Predicates27634 +Node: Type Predicates27958 +Node: Equality Predicates33011 +Node: Control Structure35797 +Node: Assignment36605 +Node: Generalized Variables37855 +Node: Basic Setf39170 +Node: Modify Macros46435 +Node: Customizing Setf53668 +Node: Variable Bindings60974 +Node: Dynamic Bindings61563 +Node: Lexical Bindings62466 +Node: Function Bindings66584 +Node: Macro Bindings68985 +Node: Conditionals71912 +Node: Blocks and Exits75009 +Node: Iteration78076 +Node: Loop Facility83564 +Node: Loop Basics84499 +Node: Loop Examples87112 +Node: For Clauses89383 +Node: Iteration Clauses101272 +Node: Accumulation Clauses103125 +Node: Other Clauses105481 +Node: Multiple Values111562 +Node: Macros113465 +Node: Declarations116690 +Node: Symbols125185 +Node: Property Lists125470 +Node: Creating Symbols127671 +Node: Numbers129760 +Node: Predicates on Numbers130244 +Node: Numerical Functions131286 +Node: Random Numbers135532 +Node: Implementation Parameters138253 +Node: Sequences141844 +Node: Sequence Basics142523 +Node: Mapping over Sequences146111 +Node: Sequence Functions151987 +Node: Searching Sequences158185 +Node: Sorting Sequences161237 +Node: Lists163798 +Node: List Functions164229 +Node: Substitution of Expressions168515 +Node: Lists as Sets170415 +Node: Association Lists174500 +Node: Hash Tables176218 +Node: Structures176444 +Node: Assertions191159 +Node: Efficiency Concerns194091 +Node: Common Lisp Compatibility200465 +Node: Old CL Compatibility203643 +Node: Porting Common Lisp208056 +Node: Function Index219079 +Node: Variable Index234539 + +End Tag Table diff -u -r -N xemacs-21.4.18/info/custom.info xemacs-21.4.19/info/custom.info --- xemacs-21.4.18/info/custom.info 1969-12-31 19:00:00.000000000 -0500 +++ xemacs-21.4.19/info/custom.info 2006-01-28 18:57:48.000000000 -0500 @@ -0,0 +1,407 @@ +This is ../info/custom.info, produced by makeinfo version 4.8 from +custom.texi. + +INFO-DIR-SECTION XEmacs Editor +START-INFO-DIR-ENTRY +* Customizations: (custom). Customization Library. +END-INFO-DIR-ENTRY + + +File: custom.info, Node: Top, Next: Declaring Groups, Prev: (dir), Up: (dir) + +The Customization Library +************************* + +This manual describes how to declare customization groups, variables, +and faces. It doesn't contain any examples, but please look at the file +`cus-edit.el' which contains many declarations you can learn from. + +* Menu: + +* Declaring Groups:: +* Declaring Variables:: +* Declaring Faces:: +* Usage for Package Authors:: +* Utilities:: +* The Init File:: +* Wishlist:: + + All the customization declarations can be changes by keyword +arguments. Groups, variables, and faces all share these common +keywords: + +`:group' + VALUE should be a customization group. Add SYMBOL to that group. + +`:link' + VALUE should be a widget type. Add VALUE to the external links + for this customization option. Useful widget types include + `custom-manual', `info-link', and `url-link'. + +`:load' + Add VALUE to the files that should be loaded before displaying + this customization option. The value should be either a string, + which should be a string which will be loaded with `load-library' + unless present in `load-history', or a symbol which will be loaded + with `require'. + +`:tag' + VALUE should be a short string used for identifying the option in + customization menus and buffers. By default the tag will be + automatically created from the options name. + + +File: custom.info, Node: Declaring Groups, Next: Declaring Variables, Prev: Top, Up: Top + +Declaring Groups +================ + +Use `defgroup' to declare new customization groups. + + -- Function: defgroup symbol members doc [keyword value]... + Declare SYMBOL as a customization group containing MEMBERS. + SYMBOL does not need to be quoted. + + DOC is the group documentation. + + MEMBERS should be an alist of the form ((NAME WIDGET)...) where + NAME is a symbol and WIDGET is a widget for editing that symbol. + Useful widgets are `custom-variable' for editing variables, + `custom-face' for editing faces, and `custom-group' for editing + groups. + + Internally, custom uses the symbol property `custom-group' to keep + track of the group members, and `group-documentation' for the + documentation string. + + The following additional KEYWORD's are defined: + + `:prefix' + VALUE should be a string. If the string is a prefix for the + name of a member of the group, that prefix will be ignored + when creating a tag for that member. + + +File: custom.info, Node: Declaring Variables, Next: Declaring Faces, Prev: Declaring Groups, Up: Top + +Declaring Variables +=================== + +Use `defcustom' to declare user editable variables. + + -- Function: defcustom symbol value doc [keyword value]... + Declare SYMBOL as a customizable variable that defaults to VALUE. + Neither SYMBOL nor VALUE needs to be quoted. If SYMBOL is not + already bound, initialize it to VALUE. + + DOC is the variable documentation. + + The following additional KEYWORD's are defined: + + `:type' + VALUE should be a widget type. + + `:options' + VALUE should be a list of possible members of the specified + type. For hooks, this is a list of function names. + + `:initialize' + VALUE should be a function used to initialize the variable. + It takes two arguments, the symbol and value given in the + `defcustom' call. Some predefined functions are: + + `custom-initialize-set' + Use the `:set' method to initialize the variable. Do not + initialize it if already bound. This is the default + `:initialize' method. + + `custom-initialize-default' + Always use `set-default' to initialize the variable, + even if a `:set' method has been specified. + + `custom-initialize-reset' + If the variable is already bound, reset it by calling + the `:set' method with the value returned by the `:get' + method. + + `custom-initialize-changed' + Like `custom-initialize-reset', but use `set-default' to + initialize the variable if it is not bound and has not + been set already. + + `:set' + VALUE should be a function to set the value of the symbol. It + takes two arguments, the symbol to set and the value to give + it. The default is `set-default'. + + `:get' + VALUE should be a function to extract the value of symbol. + The function takes one argument, a symbol, and should return + the current value for that symbol. The default is + `default-value'. + + `:require' + VALUE should be a feature symbol. Each feature will be + required when the `defcustom' is evaluated, or when Emacs is + started if the user has saved this option. + + + *Note Sexp Types: (widget)Sexp Types, for information about + widgets to use together with the `:type' keyword. + + Internally, custom uses the symbol property `custom-type' to keep +track of the variables type, `standard-value' for the program specified +default value, `saved-value' for a value saved by the user, and +`variable-documentation' for the documentation string. + + Use `custom-add-option' to specify that a specific function is +useful as a member of a hook. + + -- Function: custom-add-option symbol option + To the variable SYMBOL add OPTION. + + If SYMBOL is a hook variable, OPTION should be a hook member. For + other types of variables, the effect is undefined." + + +File: custom.info, Node: Declaring Faces, Next: Usage for Package Authors, Prev: Declaring Variables, Up: Top + +Declaring Faces +=============== + +Faces are declared with `defface'. + + -- Function: defface face spec doc [keyword value]... + Declare FACE as a customizable face that defaults to SPEC. FACE + does not need to be quoted. + + If FACE has been set with `custom-set-face', set the face + attributes as specified by that function, otherwise set the face + attributes according to SPEC. + + DOC is the face documentation. + + SPEC should be an alist of the form `((DISPLAY ATTS)...)'. + + ATTS is a list of face attributes and their values. The possible + attributes are defined in the variable `custom-face-attributes'. + + The ATTS of the first entry in SPEC where the DISPLAY matches the + frame should take effect in that frame. DISPLAY can either be the + symbol `t', which will match all frames, or an alist of the form + `((REQ ITEM...)...)' + + For the DISPLAY to match a FRAME, the REQ property of the frame + must match one of the ITEM. The following REQ are defined: + + `type' + (the value of (window-system)) + Should be one of `x' or `tty'. + + `class' + (the frame's color support) + Should be one of `color', `grayscale', or `mono'. + + `background' + (what color is used for the background text) + Should be one of `light' or `dark'. + + Internally, custom uses the symbol property `face-defface-spec' for + the program specified default face properties, `saved-face' for + properties saved by the user, and `face-documentation' for the + documentation string. + + + +File: custom.info, Node: Usage for Package Authors, Next: Utilities, Prev: Declaring Faces, Up: Top + +Usage for Package Authors +========================= + +The recommended usage for the author of a typical emacs lisp package is +to create one group identifying the package, and make all user options +and faces members of that group. If the package has more than around 20 +such options, they should be divided into a number of subgroups, with +each subgroup being member of the top level group. + + The top level group for the package should itself be member of one or +more of the standard customization groups. There exists a group for +each _finder_ keyword. Press `C-h p' to see a list of finder keywords, +and add you group to each of them, using the `:group' keyword. + + +File: custom.info, Node: Utilities, Next: The Init File, Prev: Usage for Package Authors, Up: Top + +Utilities +========= + +These utilities can come in handy when adding customization support. + + -- Widget: custom-manual + Widget type for specifying the info manual entry for a + customization option. It takes one argument, an info address. + + -- Function: custom-add-to-group group member widget + To existing GROUP add a new MEMBER of type WIDGET, If there + already is an entry for that member, overwrite it. + + -- Function: custom-add-link symbol widget + To the custom option SYMBOL add the link WIDGET. + + -- Function: custom-add-load symbol load + To the custom option SYMBOL add the dependency LOAD. LOAD should + be either a library file name, or a feature name. + + -- Function: customize-menu-create symbol &optional name + Create menu for customization group SYMBOL. If optional NAME is + given, use that as the name of the menu. Otherwise the menu will + be named `Customize'. The menu is in a format applicable to + `easy-menu-define'. + + +File: custom.info, Node: The Init File, Next: Wishlist, Prev: Utilities, Up: Top + +The Init File +============= + +Customizations are saved to the file specified by `custom-file', as +calls to `custom-set-variables' and `custom-set-faces'. + + When you save customizations, the current implementation removes the +calls to `custom-set-variables' and `custom-set-faces', and replaces +them with code generated on the basis of the current customization +state in Emacs. + + By default `custom-file' is your `.emacs' file (for GNU Emacs and +older XEmacs) and is `custom.el' in the same directory as `init.el' (in +XEmacs 21.4 and later). If you use another file, you must explicitly +load it yourself. + + As of XEmacs 21.4.7, when `custom-file' is present, it is loaded +_after_ `init.el'. This is likely to change in the future, because (1) +actions in `init.el' often would like to depend on customizations for +consistent appearance and (2) Custom is quite brutal about enforcing +its idea of the correct values at initialization. + + +File: custom.info, Node: Wishlist, Prev: The Init File, Up: Top + +Wishlist +======== + + * Better support for keyboard operations in the customize buffer. + + * Integrate with `w3' so you can get customization buffers with much + better formatting. I'm thinking about adding a + name tag. The latest w3 have some support for + this, so come up with a convincing example. + + * Add an `examples' section, with explained examples of custom type + definitions. + + * Support selectable color themes. I.e., change many faces by + setting one variable. + + * Support undo using lmi's `gnus-undo.el'. + + * Make it possible to append to `choice', `radio', and `set' options. + + * Ask whether set or modified variables should be saved in + `kill-buffer-hook'. + + Ditto for `kill-emacs-query-functions'. + + * Command to check if there are any customization options that does + not belong to an existing group. + + * Optionally disable the point-cursor and instead highlight the + selected item in XEmacs. This is like the *Completions* buffer in + XEmacs. Suggested by Jens Lautenbacher + `'. + + * Explain why it is necessary that all choices have different default + values. + + * Add some direct support for meta variables, i.e. make it possible + to specify that this variable should be reset when that variable is + changed. + + * Add tutorial. + + * Describe the `:type' syntax in this manual. + + * Find a place is this manual for the following text: + + *Radio vs. Buttons* + + Use a radio if you can't find a good way to describe the item in + the choice menu text. I.e. it is better to use a radio if you + expect the user would otherwise manually select each item from the + choice menu in turn to see what it expands too. + + Avoid radios if some of the items expands to complex structures. + + I mostly use radios when most of the items are of type + `function-item' or `variable-item'. + + * Update customize buffers when `custom-set-variable' or + `custom-save-customized' is called. + + * Better handling of saved but uninitialized items. + + * Detect when faces have been changed outside customize. + + * Enable mouse help in Emacs by default. + + * Add an easy way to display the standard settings when an item is + modified. + + * See if it is feasible to scan files for customization information + instead of loading them, + + * Add hint message when user push a non-pushable tag. + + Suggest that the user unhide if hidden, and edit the value directly + otherwise. + + * Use checkboxes and radio buttons in the state menus. + + * Add option to hide `[hide]' for short options. Default, on. + + * Add option to hide `[state]' for options with their standard + settings. + + * There should be a way to specify site defaults for user options. + + * There should be more buffer styles. The default `nested style, + the old `outline' style, a `numeric' style with numbers instead of + stars, an `empty' style with just the group name, and `compact' + with only one line per item. + + * Newline and tab should be displayed as `^J' and `^I' in the + `regexp' and `file' widgets. I think this can be done in XEmacs + by adding a display table to the face. + + * Use glyphs to draw the `customize-browse' tree. + + Add echo and balloon help. You should be able to read the + documentation simply by moving the mouse pointer above the name. + + Add parent links. + + Add colors. + + + + +Tag Table: +Node: Top204 +Node: Declaring Groups1622 +Node: Declaring Variables2721 +Node: Declaring Faces5814 +Node: Usage for Package Authors7510 +Node: Utilities8286 +Node: The Init File9372 +Node: Wishlist10399 + +End Tag Table diff -u -r -N xemacs-21.4.18/info/emodules.info xemacs-21.4.19/info/emodules.info --- xemacs-21.4.18/info/emodules.info 1969-12-31 19:00:00.000000000 -0500 +++ xemacs-21.4.19/info/emodules.info 2006-01-28 18:57:48.000000000 -0500 @@ -0,0 +1,984 @@ +This is ../info/emodules.info, produced by makeinfo version 4.8 from +emodules.texi. + + This file documents the module loading technology of XEmacs. + + Copyright (C) 1998 J. Kean Johnston. + + Permission is granted to make and distribute verbatim copies of this +manual provided the copyright notice and this permission notice are +preserved on all copies. + + Permission is granted to copy and distribute modified versions of +this manual under the conditions for verbatim copying, provided that the +entire resulting derived work is distributed under the terms of a +permission notice identical to this one. + + Permission is granted to copy and distribute translations of this +manual into another language, under the above conditions for modified +versions, except that this permission notice may be stated in a +translation approved by the Foundation. + + Permission is granted to copy and distribute modified versions of +this manual under the conditions for verbatim copying, provided also +that the section entitled "GNU General Public License" is included +exactly as in the original, and provided that the entire resulting +derived work is distributed under the terms of a permission notice +identical to this one. + + Permission is granted to copy and distribute translations of this +manual into another language, under the above conditions for modified +versions, except that the section entitled "GNU General Public License" +may be included in a translation approved by the Free Software +Foundation instead of in the original English. + + +File: emodules.info, Node: Top, Next: Introduction, Prev: (dir), Up: (dir) + + This Info file contains v1.0 of the XEmacs dynamic loadable module +support documentation. + +* Menu: + +* Introduction:: Introducing Emacs Modules +* Anatomy of a Module:: Basic module layout and technology +* Using ellcc:: How to use the module compiler +* Defining Functions:: Creating new Lisp primitives +* Defining Variables:: Creating new Lisp variables +* Index:: Concept Index + + --- The Detailed Node Listing --- + +Anatomy of a Module + +* Required Header File:: Always include +* Required Functions:: Functions you must always provide +* Required Variables:: Variables whose values you must provide +* Loading other Modules:: How to load dependent modules + +Using `ellcc' + +* Compile Mode:: Compiling modules using ellcc +* Initialization Mode:: Generating documentation and variables +* Link Mode:: Creating the final loadable module +* Other ellcc options:: Other useful options +* Environment Variables:: How to control ellcc + +Defining Functions + +* Using DEFUN:: Using the DEFUN macro to define functions +* Declaring Functions:: Declaring functions to the Lisp reader + + +File: emodules.info, Node: Introduction, Next: Anatomy of a Module, Prev: Top, Up: Top + +1 Introduction +************** + +XEmacs is a powerful, extensible editor. The traditional way of +extending the functionality of XEmacs is to use its built-in Lisp +language (called Emacs Lisp, or Elisp for short). However, while Elisp +is a full programming language and capable of extending XEmacs in more +ways than you can imagine, it does have its short-comings. + + Firstly, Elisp is an interpreted language, and this has serious speed +implications. Like all other interpreted languages (like Java), Elisp +is often suitable only for certain types of application or extension. +So although Elisp is a general purpose language, and very high level, +there are times when it is desirable to descend to a lower level +compiled language for speed purposes. + + Secondly, Elisp (or Lisp in general) is not a very common language +any more, except for certain circles in the computer industry. C is a +far more commonly known language, and because it is compiled, more +suited to a wider range of applications, especially those that require +low level access to a system or need to be as quick as possible. + + This manual describes a new way of extending XEmacs, by using dynamic +loadable modules (also known as dynamically loadable libraries (DLLs), +dynamic shared objects (DSOs) or just simply shared objects), which can +be written in C or C++ and loaded into XEmacs at any time. I sometimes +refer to this technology as "CEmacs", which is short for "C Extensible +Emacs". + + XEmacs modules are configured into and installed with XEmacs by +default on all systems that support loading of shared objects. From a +users perspective, the internals of XEmacs modules are irrelevant. All +a user will ever need to know about shared objects is the name of the +shared object when they want to load a given module. From a developers +perspective though, a lot more is provided. + + * Of primary interest is the `ellcc' program. This program is + created during compile time, and is intended to abstract compiler + specific characteristics from the developer. This program is + called to compile and link all objects that will make up the final + shared object, and accepts all common C compiler flags. `ellcc' + also sets up the correct environment for compiling modules by + enabling any special compiler modes (such as PIC mode), setting + the correct include paths for the location of XEmacs internal + header files etc. The program will also invoke the linker + correctly to created the final shared object which is loaded into + XEmacs. + + * CEmacs also makes all of the relevant XEmacs internal header + files available for module authors to use. This is often required + to get data structure definitions and external variable + declarations. The header files installed include the module + specific header file `emodules.h'. Due to the nature of dynamic + modules, most of the internals of XEmacs are exposed. *Note Top: + (internals)Top, for a more complete discussion on how to extend + and understand XEmacs. All of the rules for C modules are + discussed there. + + * Part of the XEmacs distribution is a set of sample modules. + These are not installed when XEmacs is, but remain in the XEmacs + source tree. These modules live in the directory `modules', which + is a sub-directory of the main XEmacs source code directory. + Please look at the samples carefully, and maybe even use them as a + basis for making your own modules. Most of the concepts required + for writing extension modules are covered in the samples. + + * Last, but not least is this manual. This can be viewed from + within XEmacs, and it can be printed out as well. It is the + intention of this document that it will describe everything you + need to know about extending XEmacs in C. If you do not find this + to be the case, please contact the author(s). + + The rest of this document will discuss the actual mechanics of +XEmacs modules and work through several of the samples. Please be sure +that you have read the XEmacs Internals Manual and understand +everything in it. The concepts there apply to all modules. This +document may have some overlap, but it is the internals manual which +should be considered the final authority. It will also help a great +deal to look at the actual XEmacs source code to see how things are +done. + + +File: emodules.info, Node: Anatomy of a Module, Next: Using ellcc, Prev: Introduction, Up: Top + +2 Anatomy of a Module +********************* + +Each dynamically loadable XEmacs extension (hereafter referred to as a +module) has a certain compulsory format, and must contain several +pieces of information and several mandatory functions. This chapter +describes the basic layout of a module, and provides a very simple +sample. The source for this sample can be found in the file +`modules/simple/sample.c' in the main XEmacs source code tree. + +* Menu: + +* Required Header File:: Always include +* Required Functions:: Functions you must always provide +* Required Variables:: Variables whose values you must provide +* Loading other Modules:: How to load dependent modules + + +File: emodules.info, Node: Required Header File, Next: Required Functions, Prev: Anatomy of a Module, Up: Anatomy of a Module + +2.1 Required Header File +======================== + +Every module must include the file `'. This will include +several other XEmacs internal header files, and will set up certain +vital macros. One of the most important files included by `emodules.h' +is the generated `config.h' file, which contains all of the required +system abstraction macros and definitions. Most modules will probably +require some pre-processor conditionals based on constants defined in +`config.h'. Please read that file to familiarize yourself with the +macros defined there. + + Depending on exactly what your module will be doing, you will +probably need to include one or more of the XEmacs internal header +files. When you `#include ', you will get a few of the +most important XEmacs header files included automatically for you. The +files included are: + +`lisp.h' + This file contains most of the macros required for declaring Lisp + object types, macros for accessing Lisp objects, and global + variable declarations. + +`sysdep.h' + All system dependent declarations and abstraction macros live + here. You should never call low level system functions directly. + Rather, you should use the abstraction macros provided in this + header file. + +`window.h' + This header file defines the window structures and Lisp types, and + provides functions and macros for manipulating multiple XEmacs + windows. + +`buffer.h' + All macros and function declarations for manipulating internal and + user visible buffers appear in this file. + +`insdel.h' + This header provides the information required for performing text + insertion and deletion. + +`frame.h' + Provides the required structure, macro and function definitions for + manipulating XEmacs frames. + + +File: emodules.info, Node: Required Functions, Next: Required Variables, Prev: Required Header File, Up: Anatomy of a Module + +2.2 Required Functions +====================== + +Every module requires several initialization functions. It is the +responsibility of these functions to load in any dependent modules, and +to declare all variables and functions which are to be made visible to +the XEmacs Lisp reader. Each of these functions performs a very +specific task, and they are executed in the correct order by XEmacs. +All of these functions are `void' functions which take no arguments. +Here, briefly, are the required module functions. Note that the actual +function names do not end with the string `_module', but rather they +end with the abbreviated module name by which the module is known. +More on the module name and its importance later. Just bear in mind +that the text `_module' in the functions below is simply a +place-holder, not an actual function name. + +`syms_of_module' + This required function is responsible for introducing to the Lisp + reader all functions that you have defined in your module using + `DEFUN()'. Note that _only_ functions are declared here, using + the `DEFSUBR()' macro. No variables are declared. + +`vars_of_module' + This required function contains calls to macros such as + `DEFVAR_LISP()', `DEFVAR_BOOL()' etc, and its purpose is to + declare and initialize all and any variables that your module + defines. They syntax for declaring variables is identical to the + syntax used for all internal XEmacs source code. If the module is + intended to be usable statically linked into XEmacs, the actions + of this function are severely restricted. *Note General Coding + Rules: (internals)General Coding Rules. Also see the comments in + `src/emacs.c' (`main_1'). Modules which perform initializations + not permitted by these rules will probably work, but dual-use + (dynamic loading and static linking) modules will require very + careful, and possibly fragile, coding. + +`modules_of_module' + This optional function should be used to load in any modules which + your module depends on. The XEmacs module loading code makes sure + that the same module is not loaded twice, so several modules can + safely call the module load function for the same module. Only + one copy of each module (at a given version) will ever be loaded. + +`docs_of_module' + This is a required function, but not one which you need ever write. + This function is created automatically by `ellcc' when the module + initialization code is produced. It is required to document all + functions and variables declared in your module. + + +File: emodules.info, Node: Required Variables, Next: Loading other Modules, Prev: Required Functions, Up: Anatomy of a Module + +2.3 Required Variables +====================== + +Not only does a module need to declare the initialization functions +mentioned above, it is also required to provide certain variables which +the module loading code searches for in order to determine the viability +of a module. You are _not_ required to provide these variables in your +source files. They are automatically set up in the module +initialization file by the `ellcc' compiler. These variables are +discussed here simply for the sake of completeness. + +`emodules_compiler' + This is a variable of type `long', and is used to indicate the + version of the XEmacs loading technology that was used to produce + the module being loaded. This version number is completely + unrelated to the XEmacs version number, as a given module may + quite well work regardless of the version of XEmacs that was + installed at the time the module was created. + + The XEmacs modules version is used to differentiate between major + changes in the module loading technology, not versions of XEmacs. + +`emodules_name' + This is a short (typically 10 characters or less) name for the + module, and it is used as a suffix for all of the required + functions. This is also the name by which the module is + recognized when loading dependent modules. The name does not + necessarily have to be the same as the physical file name, + although keeping the two names in sync is a pretty good idea. The + name must not be empty, and it must be a valid part of a C + function name. The value of this variable is appended to the + function names `syms_of_', `vars_of_', `modules_of_' and + `docs_of_' to form the actual function names that the module + loading code looks for when loading a module. + + This variable is set by the `--mod-name' argument to `ellcc'. + +`emodules_version' + This string variable is used to load specific versions of a module. + Rarely will two or more versions of a module be left lying around, + but just in case this does happen, this variable can be used to + control exactly which module should be loaded. See the Lisp + function `load-module' for more details. This variable is set by + the `--mod-version' argument to `ellcc'. + +`emodules_title' + This is a string which describes the module, and can contain + spaces or other special characters. It is used solely for + descriptive purposes, and does not affect the loading of the + module. The value is set by the `--mod-title' argument to `ellcc'. + + +File: emodules.info, Node: Loading other Modules, Prev: Required Variables, Up: Anatomy of a Module + +2.4 Loading other Modules +========================= + +During the loading of a module, it is the responsibility of the function +`modules_of_module' to load in any modules which the current module +depends on. If the module is stand-alone, and does not depend on other +modules, then this function can be left empty or even undeclared. +However, if it does have dependencies, it must call `emodules_load': + + int emodules_load (const char *module, + const char *modname, + const char *modver) + + The first argument MODULE is the name of the actual shared object or +DLL. You can omit the `.so', `.ell' or `.dll' extension of you wish. +If you do not specify an absolute path name, then the same rules as +apply to loading Lisp modules are applied when searching for the +module. If the module cannot be found in any of the standard places, +and an absolute path name was not specified, `emodules_load' will +signal an error and loading of the module will stop. + + The second argument (MODNAME) is the module name to load, and must +match the contents of the variable EMODULE_NAME in the module to be +loaded. A mis-match will cause the module load to fail. If this +parameter is `NULL' or empty, then no checks are performed against the +target module's EMODULE_NAME variable. + + The last argument, MODVER, is the desired version of the module to +load, and is compared to the target module's EMODULE_VERSION value. If +this parameter is not `NULL' or empty, and the match fails, then the +load of the module will fail. + + `emodules_load' can be called recursively. If, at any point during +the loading of modules a failure is encountered, then all modules that +were loaded since the top level call to `emodules_load' will be +unloaded. This means that if any child modules fail to load, then +their parents will also fail to load. This does not include previous +successful calls to `emodules_load' at the top level. + + *Warning:* Modules are _not_ loaded with the `RTLD_GLOBAL' flag. +The practical upshot is that individual modules do not have access to +each other's C symbols. One module cannot make a C function call to a +function defined in another module, nor can it read or set a C variable +in another module. All interaction between modules must, therefore, +take place at the Lisp level. This is by design. Other projects have +attempted to use `RTLD_GLOBAL', only to find that spurious symbol name +clashes were the result. Helper functions often have simple names, +increasing the probability of such a clash. If you really need to +share symbols between modules, create a shared library containing those +symbols, and link your modules with that library. Otherwise, +interactions between modules must take place via Lisp function calls +and Lisp variables accesses. + + +File: emodules.info, Node: Using ellcc, Next: Defining Functions, Prev: Anatomy of a Module, Up: Top + +3 Using `ellcc' +*************** + +Before discussing the anatomy of a module in greater detail, you should +be aware of the steps required in order to correctly compile and link a +module for use within XEmacs. There is little difference between +compiling normal C code and compiling a module. In fact, all that +changes is the command used to compile the module, and a few extra +arguments to the compiler. + + XEmacs now ships with a new user utility, called `ellcc'. This is +the "Emacs Loadable Library C Compiler". This is a wrapper program +that will invoke the real C compiler with the correct arguments to +compile and link your module. With the exception of a few command line +options, this program can be considered a replacement for your C +compiler. It accepts all of the same flags and arguments that your C +compiler does, so in many cases you can simply set the `make' variable +`CC' to `ellcc' and your code will be compiled as an Emacs module +rather than a static C object. + + `ellcc' has three distinct modes of operation. It can be run in +compile, link or initialization mode. These modes are discussed in more +detail below. If you want `ellcc' to show the commands it is +executing, you can specify the option `--mode=verbose' to `ellcc'. +Specifying this option twice will enable certain extra debugging +messages to be displayed on the standard output. + +* Menu: + +* Compile Mode:: Compiling modules using ellcc +* Initialization Mode:: Generating documentation and variables +* Link Mode:: Creating the final loadable module +* Other ellcc options:: Other useful options +* Environment Variables:: How to control ellcc + + +File: emodules.info, Node: Compile Mode, Next: Initialization Mode, Prev: Using ellcc, Up: Using ellcc + +3.1 Compile Mode +================ + +By default, `ellcc' is in "compile" mode. This means that it assumes +that all of the command line arguments are C compiler arguments, and +that you want to compile the specified source file or files. You can +force compile mode by specifying the `--mode=compile' argument to +`ellcc'. + + In this mode, `ellcc' is simply a front-end to the same C compiler +that was used to create the XEmacs binary itself. All `ellcc' does in +this mode is insert a few extra command line arguments before the +arguments you specify to `ellcc' itself. `ellcc' will then invoke the +C compiler to compile your module, and will return the same exit codes +and messages that your C compiler does. + + By far the easiest way to compile modules is to construct a +`Makefile' as you would for a normal program, and simply insert, at +some appropriate place something similar to: + + CC=ellcc --mode=compile + + .c.o: + $(CC) $(CFLAGS) -c $< + + After this, all you need to do is provide simple `make' rules for +compiling your module source files. Since modules are most useful when +they are small and self-contained, most modules will have a single +source file, aside from the module specific initialization file (see +below for details). + + +File: emodules.info, Node: Initialization Mode, Next: Link Mode, Prev: Compile Mode, Up: Using ellcc + +3.2 Initialization Mode +======================= + +XEmacs uses a rather bizarre way of documenting variables and +functions. Rather than have the documentation for compiled functions +and variables passed as static strings in the source code, the +documentation is included as a C comment. A special program, called +`make-docfile', is used to scan the source code files and extract the +documentation from these comments, producing the XEmacs `DOC' file, +which the internal help engine scans when the documentation for a +function or variable is requested. + + Due to the internal construction of Lisp objects, subrs and other +such things, adding documentation for a compiled function or variable +in a compiled module, at any time after XEmacs has been "dumped" is +somewhat problematic. Fortunately, as a module writer you are insulated +from the difficulties thanks to your friend `ellcc' and some internal +trickery in the module loading code. This is all done using the +"initialization" mode of `ellcc'. + + The result of running `ellcc' in initialization mode is a C source +file which you compile with (you guessed it) `ellcc' in compile mode. +Initialization mode is where you set the module name, version, title +and gather together all of the documentation strings for the functions +and variables in your module. There are several options that you are +required to pass `ellcc' in initialization mode, the first of which is +the mode switch itself, `--mode=init'. + + Next, you need to specify the name of the C source code file that +`ellcc' will produce, and you specify this using the +`--mod-output=FILENAME' argument. FILENAME is the name of the C source +code file that will contain the module variables and `docs_of_module' +function. + + As discussed previously, each module requires a short "handle" or +module name. This is specified with the `--mod-name=NAME' option, +where NAME is the abbreviated module name. This NAME must consist only +of characters that are valid in C function and variable names. + + The module version is specified using `--mod-version=VERSION' +argument, with VERSION being any arbitrary version string. This +version can be passed as an optional second argument to the Lisp +function `load-module', and as the third argument to the internal +module loading command `emodules_load'. This version string is used to +distinguish between different versions of the same module, and to +ensure that the module is loaded at a specific version. + + Last, but not least, is the module title. Specified using the +`--mod-title=TITLE' option, the specified TITLE is used when the list +of loaded modules is displayed. The module title serves no purpose +other than to inform the user of the function of the module. This +string should be brief, as it has to be formatted to fit the screen. + + Following all of these parameters, you need to provide the list of +all source code modules that make up your module. These are the files +which are scanned by `make-docfile', and provide the information +required to populate the `docs_of_module' function. Below is a sample +`Makefile' fragment which indicates how all of this is used. + + CC=ellcc --mode=compile + LD=ellcc --mode=link + MODINIT=ellcc --mode=init + CFLAGS=-O2 -DSOME_STUFF + + .c.o: + $(CC) $(CFLAGS) -c $< + + MODNAME=sample + MODVER=1.0.0 + MODTITLE="Small sample module" + + SRCS=modfile1.c modfile2.c modfile3.c + OBJS=$(SRCS:.c=.o) + + all: sample.ell + clean: + rm -f $(OBJS) sample_init.o sample.ell + + install: all + mkdir `ellcc --mod-location`/mymods > /dev/null + cp sample.ell `ellcc --mod-location`/mymods/sample.ell + + sample.ell: $(OBJS) sample_init.o + $(LD) --mod-output=$ $(OBJS) sample_init.o + + sample_init.o: sample_init.c + sample_init.c: $(SRCS) + $(MODINIT) --mod-name=$(MODNAME) --mod-version=$(MODVER) \ + --mod-title=$(MODTITLE) --mod-output=$ $(SRCS) + + The above `Makefile' is, in fact, complete, and would compile the +sample module, and optionally install it. The `--mod-location' +argument to `ellcc' will produce, on the standard output, the base +location of the XEmacs module directory. Each sub-directory of that +directory is automatically searched for modules when they are loaded +with `load-module'. An alternative location would be +`/usr/local/lib/xemacs/site-modules'. That path can change depending +on the options the person who compiled XEmacs chose, so you can always +determine the correct site location using the `--mod-site-location' +option. This directory is treated the same way as the main module +directory. Each sub-directory within it is searched for a given module +when the user attempts to load it. The valid extensions that the +loader attempts to use are `.so', `.ell' and `.dll'. You can use any +of these extensions, although `.ell' is the preferred extension. + + +File: emodules.info, Node: Link Mode, Next: Other ellcc options, Prev: Initialization Mode, Up: Using ellcc + +3.3 Link Mode +============= + +Once all of your source code files have been compiled (including the +generated init file) you need to link them all together to create the +loadable module. To do this, you invoke `ellcc' in link mode, by +passing the `--mode=link' option. You need to specify the final output +file using the `--mod-output=NAME' option, but other than that all +other arguments are passed on directly to the system compiler or +linker, along with any other required arguments to create the loadable +module. + + The module has complete access to all symbols that were present in +the dumped XEmacs, so you do not need to link against libraries that +were linked in with the main executable. If your library uses some +other extra libraries, you will need to link with those. There is +nothing particularly complicated about link mode. All you need to do +is make sure you invoke it correctly in the `Makefile'. See the sample +`Makefile' above for an example of a well constructed `Makefile' that +invoked the linker correctly. + + +File: emodules.info, Node: Other ellcc options, Next: Environment Variables, Prev: Link Mode, Up: Using ellcc + +3.4 Other `ellcc' options +========================= + +Aside from the three main `ellcc' modes described above, `ellcc' can +accept several other options. These are typically used in a `Makefile' +to determine installation paths. `ellcc' also allows you to over-ride +several of its built-in compiler and linker options using environment +variables. Here is the complete list of options that `ellcc' accepts. + +`--mode=compile' + Enables compilation mode. Use this to compile source modules. + +`--mode=link' + Enabled link edit mode. Use this to create the final module. + +`--mode=init' + Used to create the documentation function and to initialize other + required variables. Produces a C source file that must be + compiled with `ellcc' in compile mode before linking the final + module. + +`--mode=verbose' + Enables verbose mode. This will show you the commands that are + being executed, as well as the version number of `ellcc'. If you + specify this option twice, then some extra debugging information + is displayed. + +`--mod-name=NAME' + Sets the short internal module NAME to the string specified, which + must consist only of valid C identifiers. Required during + initialization mode. + +`--mod-version=VERSION' + Sets the internal module VERSION to the specified string. + Required during initialization mode. + +`--mod-title=TITLE' + Sets the module descriptive TITLE to the string specified. This + string can contain any printable characters, but should not be too + long. It is required during initialization mode. + +`--mod-output=FILENAME' + Used to control the output file name. This is used during + initialization mode to set the name of the C source file that will + be created to FILENAME. During link mode, it sets the name of the + final loadable module to FILENAME. + +`--mod-location' + This will print the name of the standard module installation path + on the standard output and immediately exit `ellcc'. Use this + option to determine the directory prefix of where you should + install your modules. + +`--mod-site-location' + This will print the name of the site specific module location and + exit. + +`--mod-archdir' + Prints the name of the root of the architecture-dependent + directory that XEmacs searches for architecture-dependent files. + +`--mod-config' + Prints the name of the configuration for which XEmacs and `ellcc' + were compiled. + + +File: emodules.info, Node: Environment Variables, Prev: Other ellcc options, Up: Using ellcc + +3.5 Environment Variables +========================= + +During its normal operation, `ellcc' uses the compiler and linker flags +that were determined at the time XEmacs was configured. In certain +rare circumstances you may wish to over-ride the flags passed to the +compiler or linker, and you can do so using environment variables. The +table below lists all of the environment variables that `ellcc' +recognizes. + +`ELLCC' + This is used to over-ride the name of the C compiler that is + invoked by `ellcc'. + +`ELLLD' + Sets the name of the link editor to use to created the final + module. + +`ELLCFLAGS' + Sets the compiler flags passed on when compiling source modules. + This only sets the basic C compiler flags. There are certain + hard-coded flags that will always be passed. + +`ELLLDFLAGS' + Sets the flags passed on to the linker. This does *not* include + the flags for enabling PIC mode. This just sets basic linker + flags. + +`ELLDLLFLAGS' + Sets the flags passed to the linker that are required to created + shared and loadable objects. + +`ELLPICFLAGS' + Sets the C compiler option required to produce an object file that + is suitable for including in a shared library. This option should + turn on PIC mode, or the moral equivalent thereof on the target + system. + +`ELLMAKEDOC' + Sets the name of the `make-docfile' program to use. Usually + `ellcc' will use the version that was compiled and installed with + XEmacs, but this option allows you to specify an alternative path. + Used during the compile phase of XEmacs itself. + + +File: emodules.info, Node: Defining Functions, Next: Defining Variables, Prev: Using ellcc, Up: Top + +4 Defining Functions +******************** + +One of the main reasons you would ever write a module is to provide one +or more "functions" for the user or the editor to use. The term +"function" is a bit overloaded here, as it refers to both a C function +and the way it appears to Lisp, which is a "subroutine", or simply a +"subr". A Lisp subr is also known as a Lisp primitive, but that term +applies less to dynamic modules. *Note Writing Lisp Primitives: +(internals)Writing Lisp Primitives, for details on how to declare +functions. You should familiarize yourself with the instructions +there. The format of the function declaration is identical in modules. + + Normal Lisp primitives document the functions they defining by +including the documentation as a C comment. During the build process, +a program called `make-docfile' is run, which will extract all of these +comments, build up a single large documentation file, and will store +pointers to the start of each documentation entry in the dumped XEmacs. +This, of course, will not work for dynamic modules, as they are loaded +long after XEmacs has been dumped. For this reason, we require a +special means for adding documentation for new subrs. This is what the +macro `CDOCSUBR' is used for, and this is used extensively during +`ellcc' initialization mode. + + When using `DEFUN' in normal XEmacs C code, the sixth "parameter" is +a C comment which documents the function. For a dynamic module, we of +course need to convert the C comment to a usable string, and we need to +set the documentation pointer of the subr to this string. As a module +programmer, you don't actually need to do any work for this to happen. +It is all taken care of in the `docs_of_module' function created by +`ellcc'. + +* Menu: + +* Using DEFUN:: Using the DEFUN macro to define functions +* Declaring Functions:: Declaring functions to the Lisp reader + + +File: emodules.info, Node: Using DEFUN, Next: Declaring Functions, Prev: Defining Functions, Up: Defining Functions + +4.1 Using `DEFUN' +================= + +Although the full syntax of a function declaration is discussed in the +XEmacs internals manual in greater depth, what follows is a brief +description of how to define and implement a new Lisp primitive in a +module. This is done using the `DEFUN' macro. Here is a small example: + + DEFUN ("my-function", Fmy_function, 1, 1, "FFile name: ", /* + Sample Emacs primitive function. + + The specified FILE is frobnicated before it is fnozzled. + */ + (file)) + { + char *filename; + + if (NILP(file)) + return Qnil; + + filename = (char *)XSTRING_DATA(file); + frob(filename); + return Qt; + } + + The first argument is the name of the function as it will appear to +the Lisp reader. This must be provided as a string. The second +argument is the name of the actual C function that will be created. +This is typically the Lisp function name with a preceding capital `F', +with hyphens converted to underscores. This must be a valid C function +name. Next come the minimum and maximum number of arguments, +respectively. This is used to ensure that the correct number of +arguments are passed to the function. Next is the `interactive' +definition. If this function is meant to be run by a user +interactively, then you need to specify the argument types and prompts +in this string. Please consult the XEmacs Lisp manual for more +details. Next comes a C comment that is the documentation for this +function. This comment *must* exist. Last comes the list of function +argument names, if any. + + +File: emodules.info, Node: Declaring Functions, Prev: Using DEFUN, Up: Defining Functions + +4.2 Declaring Functions +======================= + +Simply writing the code for a function is not enough to make it +available to the Lisp reader. You have to, during module +initialization, let the Lisp reader know about the new function. This +is done by calling `DEFSUBR' with the name of the function. This is +the sole purpose of the initialization function `syms_of_module'. +*Note Required Functions::, for more details. + + Each call to `DEFSUBR' takes as its only argument the name of the +function, which is the same as the second argument to the call to +`DEFUN'. Using the example function above, you would insert the +following code in the `syms_of_module' function: + + DEFSUBR(Fmy_function); + + This call will instruct XEmacs to make the function visible to the +Lisp reader and will prepare for the insertion of the documentation into +the right place. Once this is done, the user can call the Lisp +function `my-function', if it was defined as an interactive function +(which in this case it was). + + Thats all there is to defining and announcing new functions. The +rules for what goes inside the functions, and how to write good +modules, is beyond the scope of this document. Please consult the +XEmacs internals manual for more details. + + +File: emodules.info, Node: Defining Variables, Next: Index, Prev: Defining Functions, Up: Top + +5 Defining Variables +******************** + +Rarely will you write a module that only contains functions. It is +common to also provide variables which can be used to control the +behavior of the function, or store the results of the function being +executed. The actual C variable types are the same for modules and +internal XEmacs primitives, and the declaration of the variables is +identical. + + *Note Adding Global Lisp Variables: (internals)Adding Global Lisp +Variables, for more information on variables and naming conventions. + + Once your variables are defined, you need to initialize them and make +the Lisp reader aware of them. This is done in the `vars_of_module' +initialization function using special XEmacs macros such as +`DEFVAR_LISP', `DEFVAR_BOOL', `DEFVAR_INT' etc. The best way to see +how to use these macros is to look at existing source code, or read the +internals manual. + + One _very_ important difference between XEmacs variables and module +variables is how you use pure space. Simply put, you *never* use pure +space in XEmacs modules. The pure space storage is of a limited size, +and is initialized properly during the dumping of XEmacs. Because +variables are being added dynamically to an already running XEmacs when +you load a module, you cannot use pure space. Be warned: *do not use +pure space in modules. Repeat, do not use pure space in modules.* +Once again, to remove all doubts: *DO NOT USE PURE SPACE IN MODULES!!!* + + Below is a small example which declares and initializes two +variables. You will note that this code takes into account the fact +that this module may very well be compiled into XEmacs itself. This is +a prudent thing to do. + + Lisp_Object Vsample_string; + int sample_boolean; + + void + vars_of_module() + { + DEFVAR_LISP ("sample-string", &Vsample_string /* + This is a sample string, declared in a module. + + Nothing magical about it. + */); + + DEFVAR_BOOL("sample-boolean", &sample_boolean /* + *Sample user-settable boolean. + */); + + sample_boolean = 0; + Vsample_string = build_string("My string"); + } + + +File: emodules.info, Node: Index, Prev: Defining Variables, Up: Top + +Index +***** + +[index] +* Menu: + +* anatomy: Anatomy of a Module. (line 6) +* compiler: Introduction. (line 39) +* compiling: Compile Mode. (line 6) +* config.h: Required Header File. (line 6) +* defining functions: Defining Functions. (line 6) +* defining objects: Defining Variables. (line 6) +* defining variables: Defining Variables. (line 6) +* DEFSUBR: Declaring Functions. (line 6) +* DEFUN: Using DEFUN. (line 6) +* DEFVAR_BOOL: Defining Variables. (line 6) +* DEFVAR_INT: Defining Variables. (line 6) +* DEFVAR_LISP: Defining Variables. (line 6) +* dependencies: Loading other Modules. + (line 6) +* DLL: Introduction. (line 25) +* docs_of_module: Required Functions. (line 47) +* documentation <1>: Initialization Mode. (line 6) +* documentation: Introduction. (line 69) +* DSO: Introduction. (line 25) +* ELLCC: Environment Variables. + (line 14) +* ellcc <1>: Using ellcc. (line 6) +* ellcc: Introduction. (line 39) +* ELLCFLAGS: Environment Variables. + (line 22) +* ELLDLLFLAGS: Environment Variables. + (line 32) +* ELLLD: Environment Variables. + (line 18) +* ELLLDFLAGS: Environment Variables. + (line 27) +* ELLMAKEDOC: Environment Variables. + (line 42) +* ELLPICFLAGS: Environment Variables. + (line 36) +* Emacs Modules: Introduction. (line 25) +* emodules.h: Required Header File. (line 6) +* emodules_load: Loading other Modules. + (line 6) +* environment variables: Environment Variables. + (line 6) +* format, module: Anatomy of a Module. (line 6) +* functions, declaring: Declaring Functions. (line 6) +* functions, defining: Using DEFUN. (line 6) +* functions, Lisp: Using DEFUN. (line 6) +* functions, required: Required Functions. (line 6) +* header files: Introduction. (line 51) +* help: Introduction. (line 69) +* include files: Required Header File. (line 6) +* initialization <1>: Initialization Mode. (line 6) +* initialization <2>: Required Variables. (line 6) +* initialization: Required Functions. (line 6) +* linker: Introduction. (line 39) +* linking: Link Mode. (line 6) +* module compiler: Using ellcc. (line 6) +* module format: Anatomy of a Module. (line 6) +* module skeleton: Anatomy of a Module. (line 6) +* modules_of_module <1>: Loading other Modules. + (line 6) +* modules_of_module: Required Functions. (line 40) +* objects, defining: Defining Variables. (line 6) +* objects, Lisp: Defining Variables. (line 6) +* paths: Other ellcc options. (line 6) +* required functions: Required Functions. (line 6) +* required header: Required Header File. (line 6) +* required variables: Required Variables. (line 6) +* samples: Introduction. (line 61) +* shared object: Introduction. (line 25) +* skeleton, module: Anatomy of a Module. (line 6) +* subrs: Using DEFUN. (line 6) +* syms_of_module: Required Functions. (line 20) +* variables, defining: Defining Variables. (line 6) +* variables, Lisp: Defining Variables. (line 6) +* variables, required: Required Variables. (line 6) +* vars_of_module: Required Functions. (line 26) + + + +Tag Table: +Node: Top1536 +Node: Introduction2883 +Node: Anatomy of a Module7392 +Node: Required Header File8207 +Node: Required Functions10131 +Node: Required Variables12860 +Node: Loading other Modules15551 +Node: Using ellcc18472 +Node: Compile Mode20267 +Node: Initialization Mode21635 +Node: Link Mode26635 +Node: Other ellcc options27785 +Node: Environment Variables30369 +Node: Defining Functions32066 +Node: Using DEFUN34078 +Node: Declaring Functions35779 +Node: Defining Variables37127 +Node: Index39351 + +End Tag Table diff -u -r -N xemacs-21.4.18/info/external-widget.info xemacs-21.4.19/info/external-widget.info --- xemacs-21.4.18/info/external-widget.info 1969-12-31 19:00:00.000000000 -0500 +++ xemacs-21.4.19/info/external-widget.info 2006-01-28 18:57:48.000000000 -0500 @@ -0,0 +1,247 @@ +This is ../info/external-widget.info, produced by makeinfo version 4.8 +from external-widget.texi. + +INFO-DIR-SECTION XEmacs Editor +START-INFO-DIR-ENTRY +* External Widget: (external-widget) External Client Widget. +END-INFO-DIR-ENTRY + + +File: external-widget.info, Node: Top, Next: Using an External Client Widget, Up: (dir) + + An "external client widget" is a widget that is part of another +program but functions as an Emacs frame. This is intended to be a more +powerful replacement for standard text widgets. + +* Menu: + +* Using an External Client Widget:: +* External Client Widget Resource Settings:: +* Motif-Specific Info About the External Client Widget:: +* External Client Widget Internals:: + + +File: external-widget.info, Node: Using an External Client Widget, Next: External Client Widget Resource Settings, Prev: Top, Up: Top + +1 Using an External Client Widget +********************************* + +There are three different implementations of the external client widget. +One is designed for use in Motif applications and is linked with the +option `-lextcli_Xm'. Another is designed for non-Motif applications +that still use the X toolkit; it is linked with the option +`-lextcli_Xt'. The third is designed for applications that do not use +the X toolkit; it is linked with the option `-lextcli_Xlib'. In order +to use an external client widget in a client program that uses the X +toolkit (i.e. either of the first two options described above), simply +create an instance of widget type ExternalClient and link your program +with the appropriate library. The corresponding header file is called +`ExternalClient.h'. + + Documentation still needs to be provided for using the raw Xlib +version of the external client widget. + + The external client widget will not do anything until an instance of +Emacs is told about this particular widget. To do that, call the +function `make-frame', specifying a value for the frame parameter +`window-id'. This value should be a string containing the decimal +representation of the widget's X window ID number (this can be obtained +by the Xt function `XtWindow()'). In order for the client program to +communicate this information to Emacs, a method such as sending a +ToolTalk message needs to be used. + + Once `make-frame' has been called, Emacs will create a frame that +occupies the client widget's window. This frame can be used just like +any other frame in Emacs. + + +File: external-widget.info, Node: External Client Widget Resource Settings, Next: Motif-Specific Info About the External Client Widget, Prev: Using an External Client Widget, Up: Top + +2 External Client Widget Resource Settings +****************************************** + +The external client widget is a subclass of the Motif widget XmPrimitive +and thus inherits all its resources. In addition, the following new +resources are defined: + +`deadShell (class DeadShell)' + A boolean resource indicating whether the last request to the + ExternalShell widget that contains the frame corresponding to this + widget timed out. If true, no further requests will be made (all + requests will automatically fail) until a response to the last + request is received. This resource should normally not be set by + the user. + +`shellTimeout (class ShellTimeout)' + A value specifying how long (in milliseconds) the client should + wait for a response when making a request to the corresponding + ExternalShell widget. If this timeout is exceeded, the client + will assume that the shell is dead and will fail the request and + all subsequent requests until a response to the request is + received. Default value is 5000, or 5 seconds. + + The shell that contains the frame corresponding to an external client +widget is of type ExternalShell, as opposed to standard frames, whose +shell is of type TopLevelShell. The ExternalShell widget is a direct +subclass of Shell and thus inherits its resources. In addition, the +following new resources are defined: + +`window (class Window)' + The X window ID of the widget to use for this Emacs frame. This is + normally set by the call to `x-create-frame' and should not be + modified by the user. + +`deadClient (class DeadClient)' + A boolean resource indicating whether the last request to the + corresponding ExternalClient widget timed out. If true, no further + requests will be made (all requests will automatically fail) until + a response to the last request is received. This resource should + normally not be set by the user. + +`ClientTimeout (class ClientTimeout)' + A value specifying how long (in milliseconds) the shell should wait + for a response when making a request to the corresponding + ExternalClient widget. If this timeout is exceeded, the shell + will assume that the client is dead and will fail the request and + all subsequent requests until a response to the request is + received. Default value is 5000, or 5 seconds. + + Note that the requests that are made between the client and the shell +are primarily for handling query-geometry and geometry-manager requests +made by parent or child widgets. + + +File: external-widget.info, Node: Motif-Specific Info About the External Client Widget, Next: External Client Widget Internals, Prev: External Client Widget Resource Settings, Up: Top + +3 Motif-Specific Info About the External Client Widget +****************************************************** + +By default, the external client widget has navigation type +`XmTAB_GROUP'. + + The widget traversal keystrokes are modified slightly from the +standard XmPrimitive keystrokes. In particular, `' alone does not +traverse to the next widget (`Ctrl-' must be used instead), but +functions like a normal in Emacs. This follows the semantics of +the Motif text widget. The traversal keystrokes `Ctrl-' and +`Shift-' are silently filtered by the external client widget and +are not seen by Emacs. + + +File: external-widget.info, Node: External Client Widget Internals, Prev: Motif-Specific Info About the External Client Widget, Up: Top + +4 External Client Widget Internals +********************************** + +The following text is lifted verbatim from Ben Wing's comments in +`ExternalShell.c'. + + This is a special Shell that is designed to use an externally- +provided window created by someone else (possibly another process). +That other window should have an associated widget of class +ExternalClient. The two widgets communicate with each other using +ClientMessage events and properties on the external window. + + Ideally this feature should be independent of Emacs. Unfortunately +there are lots and lots of specifics that need to be dealt with for +this to work properly, and some of them can't conveniently be handled +within the widget's methods. Some day the code may be rewritten so +that the embedded-widget feature can be used by any application, with +appropriate entry points that are called at specific points within the +application. + + This feature is similar to the OLE (Object Linking & Embedding) +feature provided by MS Windows. + + Communication between this shell and the client widget: + + Communication is through ClientMessage events with message_type +EXTW_NOTIFY and format 32. Both the shell and the client widget +communicate with each other by sending the message to the same window +(the "external window" below), and the data.l[0] value is used to +determine who sent the message. + + The data is formatted as follows: + + data.l[0] = who sent this message: external_shell_send (0) or + external_client_send (1) data.l[1] = message type (see enum +en_extw_notify below) data.l[2-4] = data associated with this message + + EventHandler() handles messages from the other side. + + extw_send_notify_3() sends a message to the other side. + + extw_send_geometry_value() is used when an XtWidgetGeometry structure + needs to be sent. This is too much data to fit into a +ClientMessage, so the data is stored in a property and then +extw_send_notify_3() is called. + + extw_get_geometry_value() receives an XtWidgetGeometry structure +from a property. + + extw_wait_for_response() is used when a response to a sent message +is expected. It looks for a matching event within a particular +timeout. + + The particular message types are as follows: + + 1) extw_notify_init (event_window, event_mask) + + This is sent from the shell to the client after the shell realizes +its EmacsFrame widget on the client's "external window". This tells +the client that it should start passing along events of the types +specified in event_mask. event_window specifies the window of the +EmacsFrame widget, which is a child of the client's external window. + + extw_notify_init (client_type) + + When the client receives an extw_notify_init message from the shell, +it sends back a message of the same sort specifying the type of the +toolkit used by the client (Motif, generic Xt, or Xlib). + + 2) extw_notify_end () + + This is sent from the shell to the client when the shell's +EmacsFrame widget is destroyed, and tells the client to stop passing +events along. + + 3) extw_notify_qg (result) + + This is sent from the client to the shell when a QueryGeometry +request is received on the client. The XtWidgetGeometry structure +specified in the QueryGeometry request is passed on in the +EXTW_QUERY_GEOMETRY property (of type EXTW_WIDGET_GEOMETRY) on the +external window. result is unused. + + In response, the shell passes the QueryGeometry request down the +widget tree, and when a response is received, sends a message of type +extw_notify_qg back to the client, with result specifying the +GeometryResult value. If this value is XtGeometryAlmost, the returned +XtWidgetGeometry structure is stored into the same property as above. +[BPW is there a possible race condition here?] + + 4) extw_notify_gm (result) + + A very similar procedure to that for extw_notify_qg is followed when +the shell's RootGeometryManager method is called, indicating that a +child widget wishes to change the shell's geometry. The +XtWidgetGeometry structure is stored in the EXTW_GEOMETRY_MANAGER +property. + + 5) extw_notify_focus_in (), extw_notify_focus_out () + + These are sent from the client to the shell when the client gains or +loses the keyboard focus. It is done this way because Xt maintains its +own concept of keyboard focus and only the client knows this +information. + + + +Tag Table: +Node: Top232 +Node: Using an External Client Widget699 +Node: External Client Widget Resource Settings2414 +Node: Motif-Specific Info About the External Client Widget5158 +Node: External Client Widget Internals5973 + +End Tag Table diff -u -r -N xemacs-21.4.18/info/info.info xemacs-21.4.19/info/info.info --- xemacs-21.4.18/info/info.info 1969-12-31 19:00:00.000000000 -0500 +++ xemacs-21.4.19/info/info.info 2006-01-28 18:57:48.000000000 -0500 @@ -0,0 +1,840 @@ +This is ../info/info.info, produced by makeinfo version 4.8 from +info.texi. + +INFO-DIR-SECTION Texinfo documentation system +START-INFO-DIR-ENTRY +* Info: (info). Documentation browsing system. +END-INFO-DIR-ENTRY + + This file describes how to use Info, the on-line, menu-driven GNU +documentation system. + + Copyright (C) 1989, 92, 96, 97, 98, 99 Free Software Foundation, Inc. + + Permission is granted to make and distribute verbatim copies of this +manual provided the copyright notice and this permission notice are +preserved on all copies. + + Permission is granted to copy and distribute modified versions of +this manual under the conditions for verbatim copying, provided that +the entire resulting derived work is distributed under the terms of a +permission notice identical to this one. + + Permission is granted to copy and distribute translations of this +manual into another language, under the above conditions for modified +versions, except that this permission notice may be stated in a +translation approved by the Free Software Foundation. + + +File: info.info, Node: Top, Next: Getting Started, Up: (dir) + +Info: An Introduction +********************* + +Info is a program for reading documentation, which you might be using +now to read this. + + To learn how to use Info, type the command `h' while using the Info +program. It brings you to a programmed instruction sequence. + +* Menu: + +* Getting Started:: Getting started using an Info reader. +* Advanced Info:: Advanced commands within Info. +* Creating an Info File:: How to make your own Info file. + + +File: info.info, Node: Getting Started, Next: Advanced Info, Prev: Top, Up: Top + +1 Getting Started +***************** + +This first part of the Info manual describes how to get around inside +of Info. The second part of the manual describes various advanced Info +commands, and how to write an Info as distinct from a Texinfo file. +The third part is about how to generate Info files from Texinfo files. + +* Menu: + +* Help-Small-Screen:: Starting Info on a Small Screen +* Help:: How to use Info +* Help-P:: Returning to the Previous node +* Help-^L:: The Space, Rubout, B and ^L commands. +* Help-M:: Menus +* Help-Adv:: Some advanced Info commands +* Help-Q:: Quitting Info + + +File: info.info, Node: Help-Small-Screen, Next: Help, Up: Getting Started + +1.1 Starting Info on a Small Screen +=================================== + +Since your terminal has an unusually small number of lines on its +screen, it is necessary to give you special advice at the beginning. + + If you see the text `--All----' at near the bottom right corner of +the screen, it means the entire text you are looking at fits on the +screen. If you see `--Top----' instead, it means that there is more +text below that does not fit. To move forward through the text and see +another screen full, press the Space bar, . To move back up, +press the key labeled `Backspace' or . + + Here are 40 lines of junk, so you can try Spaces and Deletes and see +what they do. At the end are instructions of what you should do next. + + This is line 17 +This is line 18 +This is line 19 +This is line 20 +This is line 21 +This is line 22 +This is line 23 +This is line 24 +This is line 25 +This is line 26 +This is line 27 +This is line 28 +This is line 29 +This is line 30 +This is line 31 +This is line 32 +This is line 33 +This is line 34 +This is line 35 +This is line 36 +This is line 37 +This is line 38 +This is line 39 +This is line 40 +This is line 41 +This is line 42 +This is line 43 +This is line 44 +This is line 45 +This is line 46 +This is line 47 +This is line 48 +This is line 49 +This is line 50 +This is line 51 +This is line 52 +This is line 53 +This is line 54 +This is line 55 +This is line 56 +If you have managed to get here, go back to the beginning with Delete, +and come back here again, then you understand Space and Delete. So now +type an `n' --just one character; don't type the quotes and don't type +the Return key afterward-- to get to the normal start of the course. + + +File: info.info, Node: Help, Next: Help-P, Prev: Help-Small-Screen, Up: Getting Started + +1.2 How to use Info +=================== + +You are talking to the program Info, for reading documentation. + + Right now you are looking at one "Node" of Information. A node +contains text describing a specific topic at a specific level of +detail. This node's topic is "how to use Info". + + The top line of a node is its "header". This node's header (look at +it now) says that it is the node named `Help' in the file `info'. It +says that the `Next' node after this one is the node called `Help-P'. +An advanced Info command lets you go to any node whose name you know. + + Besides a `Next', a node can have a `Previous' or an `Up'. This +node has a `Previous' but no `Up', as you can see. + + Now it is time to move on to the `Next' node, named `Help-P'. + + >> Type `n' to move there. Type just one character; do not type +the quotes and do not type a afterward. + + `>>' in the margin means it is really time to try a command. + + +File: info.info, Node: Help-P, Next: Help-^L, Prev: Help, Up: Getting Started + +1.3 Returning to the Previous node +================================== + +This node is called `Help-P'. The `Previous' node, as you see, is +`Help', which is the one you just came from using the `n' command. +Another `n' command now would take you to the next node, `Help-^L'. + + >> But do not do that yet. First, try the `p' command, which takes + you to the `Previous' node. When you get there, you can do an `n' +again to return here. + + This all probably seems insultingly simple so far, but _do not_ be +led into skimming. Things will get more complicated soon. Also, do +not try a new command until you are told it is time to. Otherwise, you +may make Info skip past an important warning that was coming up. + + >> Now do an `n' to get to the node `Help-^L' and learn more. + + +File: info.info, Node: Help-^L, Next: Help-M, Prev: Help-P, Up: Getting Started + +1.4 The Space, Delete, B and ^L commands. +========================================= + +This node's header tells you that you are now at node `Help-^L', and +that `p' would get you back to `Help-P'. The node's title is +underlined; it says what the node is about (most nodes have titles). + + This is a big node and it does not all fit on your display screen. +You can tell that there is more that is not visible because you can see +the string `--Top-----' rather than `--All----' near the bottom right +corner of the screen. + + The Space, Delete and `B' commands exist to allow you to "move +around" in a node that does not all fit on the screen at once. Space +moves forward, to show what was below the bottom of the screen. Delete +moves backward, to show what was above the top of the screen (there is +not anything above the top until you have typed some spaces). + + >> Now try typing a Space (afterward, type a Delete to return here). + + When you type the space, the two lines that were at the bottom of +the screen appear at the top, followed by more lines. Delete takes the +two lines from the top and moves them to the bottom, _usually_, but if +there are not a full screen's worth of lines above them they may not +make it all the way to the bottom. + + If you type Space when there is no more to see, it rings the bell +and otherwise does nothing. The same goes for Delete when the header +of the node is visible. + + If your screen is ever garbaged, you can tell Info to print it out +again by typing `C-l' (`Control-L', that is--hold down "Control" and +type an or `l'). + + >> Type `C-l' now. + + To move back to the beginning of the node you are on, you can type a +lot of Deletes. You can also type simply `b' for beginning. >> Try +that now. (We have put in enough verbiage to push this past the first +screenful, but screens are so big nowadays that perhaps it isn't +enough. You may need to shrink your Emacs or Info window.) Then come +back, with Spaces. + + If your screen is very tall, all of this node might fit at once. In +that case, "b" won't do anything. Sorry; what can we do? + + You have just learned a considerable number of commands. If you +want to use one but have trouble remembering which, you should type a + which prints out a brief list of commands. When you are finished +looking at the list, make it go away by pressing repeatedly. + + >> Type a now. Press to see consecutive screenfuls of >> +the list until finished. + + From now on, you will encounter large nodes without warning, and +will be expected to know how to use Space and Delete to move around in +them without being told. Since not all terminals have the same size +screen, it would be impossible to warn you anyway. + + >> Now type `n' to see the description of the `m' command. + + +File: info.info, Node: Help-M, Next: Help-Adv, Prev: Help-^L, Up: Getting Started + +1.5 Menus +========= + +Menus and the `m' command + + With only the `n' and `p' commands for moving between nodes, nodes +are restricted to a linear sequence. Menus allow a branching +structure. A menu is a list of other nodes you can move to. It is +actually just part of the text of the node formatted specially so that +Info can interpret it. The beginning of a menu is always identified by +a line which starts with `* Menu:'. A node contains a menu if and only +if it has a line in it which starts that way. The only menu you can +use at any moment is the one in the node you are in. To use a menu in +any other node, you must move to that node first. + + After the start of the menu, each line that starts with a `*' +identifies one subtopic. The line usually contains a brief name for +the subtopic (followed by a `:'), the name of the node that talks about +that subtopic, and optionally some further description of the subtopic. +Lines in the menu that do not start with a `*' have no special +meaning--they are only for the human reader's benefit and do not define +additional subtopics. Here is an example: + + * Foo: FOO's Node This tells about FOO + + The subtopic name is Foo, and the node describing it is `FOO's Node'. +The rest of the line is just for the reader's Information. [[ But this +line is not a real menu item, simply because there is no line above it +which starts with `* Menu:'.]] + + When you use a menu to go to another node (in a way that will be +described soon), what you specify is the subtopic name, the first thing +in the menu line. Info uses it to find the menu line, extracts the +node name from it, and goes to that node. The reason that there is +both a subtopic name and a node name is that the node name must be +meaningful to the computer and may therefore have to be ugly looking. +The subtopic name can be chosen just to be convenient for the user to +specify. Often the node name is convenient for the user to specify and +so both it and the subtopic name are the same. There is an +abbreviation for this: + + * Foo:: This tells about FOO + +This means that the subtopic name and node name are the same; they are +both `Foo'. + + >> Now use Spaces to find the menu in this node, then come back to +the front with a `b' and some Spaces. As you see, a menu is +actually visible in its node. If you cannot find a menu in a node +by looking at it, then the node does not have a menu and the `m' +command is not available. + + The command to go to one of the subnodes is `m'--but _do not do it +yet!_ Before you use `m', you must understand the difference between +commands and arguments. So far, you have learned several commands that +do not need arguments. When you type one, Info processes it and is +instantly ready for another command. The `m' command is different: it +is incomplete without the "name of the subtopic". Once you have typed +`m', Info tries to read the subtopic name. + + Now look for the line containing many dashes near the bottom of the +screen. There is one more line beneath that one, but usually it is +blank. If it is empty, Info is ready for a command, such as `n' or `b' +or Space or `m'. If that line contains text ending in a colon, it +means Info is trying to read the "argument" to a command. At such +times, commands do not work, because Info tries to use them as the +argument. You must either type the argument and finish the command you +started, or type `Control-g' to cancel the command. When you have done +one of those things, the line becomes blank again. + + The command to go to a subnode via a menu is `m'. After you type +the `m', the line at the bottom of the screen says `Menu item: '. You +must then type the name of the subtopic you want, and end it with a +. + + You can abbreviate the subtopic name. If the abbreviation is not +unique, the first matching subtopic is chosen. Some menus put the +shortest possible abbreviation for each subtopic name in capital +letters, so you can see how much you need to type. It does not matter +whether you use upper case or lower case when you type the subtopic. +You should not put any spaces at the end, or inside of the item name, +except for one space where a space appears in the item in the menu. + + You can also use the "completion" feature to help enter the subtopic +name. If you type the Tab key after entering part of a name, it will +magically fill in more of the name--as much as follows uniquely from +what you have entered. + + If you move the cursor to one of the menu subtopic lines, then you do +not need to type the argument: you just type a Return, and it stands for +the subtopic of the line you are on. + + Here is a menu to give you a chance to practice. This menu gives you +three ways of going to one place, Help-FOO: + +* Menu: + +* Foo: Help-FOO. A node you can visit for fun. +* Bar: Help-FOO. Strange! two ways to get to the same place. +* Help-FOO:: And yet another! + + >> Now type just an `m' and see what happens: + + Now you are "inside" an `m' command. Commands cannot be used now; +the next thing you will type must be the name of a subtopic. + + You can change your mind about doing the `m' by typing Control-g. + + >> Try that now; notice the bottom line clear. + + >> Then type another `m'. + + >> Now type `BAR' item name. Do not type Return yet. + + While you are typing the item name, you can use the Delete key to +cancel one character at a time if you make a mistake. + + >> Type one to cancel the `R'. You could type another `R' to +replace it. You do not have to, since `BA' is a valid abbreviation. + + >> Now you are ready to go. Type a . + + After visiting Help-FOO, you should return here. + + >> Type `n' to see more commands. + + Here is another way to get to Help-FOO, a menu. You can ignore this +if you want, or else try it (but then please come back to here). + +* Menu: + +* Help-FOO:: + + +File: info.info, Node: Help-FOO, Up: Help-M + +1.5.1 The `u' command +--------------------- + +Congratulations! This is the node `Help-FOO'. Unlike the other nodes +you have seen, this one has an `Up': `Help-M', the node you just came +from via the `m' command. This is the usual convention--the nodes you +reach from a menu have `Up' nodes that lead back to the menu. Menus +move Down in the tree, and `Up' moves Up. `Previous', on the other +hand, is usually used to "stay on the same level but go backwards" + + You can go back to the node `Help-M' by typing the command `u' for +"Up". That puts you at the _front_ of the node--to get back to where +you were reading you have to type some s. + + >> Now type `u' to move back up to `Help-M'. + + +File: info.info, Node: Help-Adv, Next: Help-Q, Prev: Help-M, Up: Getting Started + +1.6 Some advanced Info commands +=============================== + +The course is almost over, so please stick with it to the end. + + If you have been moving around to different nodes and wish to +retrace your steps, the `l' command (`l' for "last") will do that, one +node-step at a time. As you move from node to node, Info records the +nodes where you have been in a special history list. The `l' command +revisits nodes in the history list; each successive `l' command moves +one step back through the history. + + If you have been following directions, ad `l' command now will get +you back to `Help-M'. Another `l' command would undo the `u' and get +you back to `Help-FOO'. Another `l' would undo the `m' and get you +back to `Help-M'. + + >> Try typing three `l''s, pausing in between to see what each +`l' does. + + Then follow directions again and you will end up back here. + + Note the difference between `l' and `p': `l' moves to where _you_ +last were, whereas `p' always moves to the node which the header says +is the `Previous' node (from this node, to `Help-M'). + + The `d' command gets you instantly to the Directory node. This +node, which is the first one you saw when you entered Info, has a menu +which leads (directly, or indirectly through other menus), to all the +nodes that exist. + + >> Try doing a `d', then do an `l' to return here (yes, _do_ +return). + + Sometimes, in Info documentation, you will see a cross reference. +Cross references look like this: *Note Cross: Help-Cross. That is a +real, live cross reference which is named `Cross' and points at the +node named `Help-Cross'. + + If you wish to follow a cross reference, you must use the `f' +command. The `f' must be followed by the cross reference name (in this +case, `Cross'). While you enter the name, you can use the Delete key +to edit your input. If you change your mind about following any +reference, you can use `Control-g' to cancel the command. + + Completion is available in the `f' command; you can complete among +all the cross reference names in the current node by typing a Tab. + + >> Type `f', followed by `Cross', and a . + + To get a list of all the cross references in the current node, you +can type `?' after an `f'. The `f' continues to await a cross +reference name even after printing the list, so if you don't actually +want to follow a reference, you should type a `Control-g' to cancel the +`f'. + + >> Type "f?" to get a list of the cross references in this node. +Then type a `Control-g' and see how the `f' gives up. + + >> Now type `n' to see the last node of the course. + + +File: info.info, Node: Help-Cross, Up: Help-Adv + +1.6.1 The node reached by the cross reference in Info +----------------------------------------------------- + +This is the node reached by the cross reference named `Cross'. + + While this node is specifically intended to be reached by a cross +reference, most cross references lead to nodes that "belong" someplace +else far away in the structure of Info. So you cannot expect the +footnote to have a `Next', `Previous' or `Up' pointing back to where +you came from. In general, the `l' (el) command is the only way to get +back there. + + >> Type `l' to return to the node where the cross reference was. + + +File: info.info, Node: Help-Q, Prev: Help-Adv, Up: Getting Started + +1.7 Quitting Info +================= + +To get out of Info, back to what you were doing before, type `q' for +"Quit". + + This is the end of the course on using Info. There are some other +commands that are meant for experienced users; they are useful, and you +can find them by looking in the directory node for documentation on +Info. Finding them will be a good exercise in using Info in the usual +manner. + + >> Type `d' to go to the Info directory node; then type `mInfo' +and Return, to get to the node about Info and see what other help is +available. + + +File: info.info, Node: Advanced Info, Next: Creating an Info File, Prev: Getting Started, Up: Top + +2 Info for Experts +****************** + +This chapter describes various advanced Info commands, and how to write +an Info as distinct from a Texinfo file. (However, in most cases, +writing a Texinfo file is better, since you can use it _both_ to +generate an Info file and to make a printed manual. *Note Overview of +Texinfo: (texinfo)Top.) + +* Menu: + +* Expert:: Advanced Info commands: g, s, e, and 1 - 5. +* Add:: Describes how to add new nodes to the hierarchy. + Also tells what nodes look like. +* Menus:: How to add to or create menus in Info nodes. +* Cross-refs:: How to add cross-references to Info nodes. +* Tags:: How to make tag tables for Info files. +* Checking:: Checking an Info File +* Emacs Info Variables:: Variables modifying the behavior of Emacs Info. + + +File: info.info, Node: Expert, Next: Add, Up: Advanced Info + +2.1 Advanced Info Commands +========================== + +`g', `s', `1', - `9', and `e' + + If you know a node's name, you can go there by typing `g', the name, +and . Thus, `gTop' would go to the node called `Top' in this +file (its directory node). `gExpert' would come back here. + + Unlike `m', `g' does not allow the use of abbreviations. + + To go to a node in another file, you can include the filename in the +node name by putting it at the front, in parentheses. Thus, +`g(dir)Top' would go to the Info Directory node, which is node +`Top' in the file `dir'. + + The node name `*' specifies the whole file. So you can look at all +of the current file by typing `g*' or all of any other file with +`g(FILENAME)'. + + The `s' command allows you to search a whole file for a string. It +switches to the next node if and when that is necessary. You type `s' +followed by the string to search for, terminated by . To search +for the same string again, just `s' followed by will do. The +file's nodes are scanned in the order they are in in the file, which +has no necessary relationship to the order that they may be in in the +tree structure of menus and `next' pointers. But normally the two +orders are not very different. In any case, you can always do a `b' to +find out what node you have reached, if the header is not visible (this +can happen, because `s' puts your cursor at the occurrence of the +string, not at the beginning of the node). + + If you grudge the system each character of type-in it requires, you +might like to use the commands `1', `2', `3', `4', ... `9'. They are +short for the `m' command together with an argument. `1' goes through +the first item in the current node's menu; `2' goes through the second +item, etc. + + If your display supports multiple fonts, and you are using Emacs' +Info mode to read Info files, the `*' for the fifth menu item is +underlined, and so is the `*' for the ninth item; these underlines make +it easy to see at a glance which number to use for an item. + + On ordinary terminals, you won't have underlining. If you need to +actually count items, it is better to use `m' instead, and specify the +name. + + The Info command `e' changes from Info mode to an ordinary Emacs +editing mode, so that you can edit the text of the current node. Type +`C-c C-c' to switch back to Info. The `e' command is allowed only if +the variable `Info-enable-edit' is non-`nil'. + + +File: info.info, Node: Add, Next: Menus, Prev: Expert, Up: Advanced Info + +2.2 Adding a new node to Info +============================= + +To add a new topic to the list in the Info directory, you must: + 1. Create some nodes, in some file, to document that topic. + + 2. Put that topic in the menu in the directory. *Note Menu: Menus. + + Usually, the way to create the nodes is with Texinfo (*note Overview +of Texinfo: (texinfo)Top.); this has the advantage that you can also +make a printed manual from them. However, if you want to edit an Info +file, here is how. + + The new node can live in an existing documentation file, or in a new +one. It must have a <^_> character before it (invisible to the user; +this node has one but you cannot see it), and it ends with either a +<^_>, a <^L>, or the end of file. Note: If you put in a <^L> to end a +new node, be sure that there is a <^_> after it to start the next one, +since <^L> cannot _start_ a node. Also, a nicer way to make a node +boundary be a page boundary as well is to put a <^L> _right after_ the +<^_>. + + The <^_> starting a node must be followed by a newline or a <^L> +newline, after which comes the node's header line. The header line +must give the node's name (by which Info finds it), and state the names +of the `Next', `Previous', and `Up' nodes (if there are any). As you +can see, this node's `Up' node is the node `Top', which points at all +the documentation for Info. The `Next' node is `Menus'. + + The keywords "Node", "Previous", "Up", and "Next", may appear in any +order, anywhere in the header line, but the recommended order is the +one in this sentence. Each keyword must be followed by a colon, spaces +and tabs, and then the appropriate name. The name may be terminated +with a tab, a comma, or a newline. A space does not end it; node names +may contain spaces. The case of letters in the names is insignificant. + + A node name has two forms. A node in the current file is named by +what appears after the `Node: ' in that node's first line. For +example, this node's name is `Add'. A node in another file is named by +`(FILENAME)NODE-WITHIN-FILE', as in `(info)Add' for this node. If the +file name starts with "./", then it is relative to the current +directory; otherwise, it is relative starting from the standard Info +file directory of your site. The name `(FILENAME)Top' can be +abbreviated to just `(FILENAME)'. By convention, the name `Top' is +used for the "highest" node in any single file--the node whose `Up' +points out of the file. The Directory node is `(dir)'. The `Top' node +of a document file listed in the Directory should have an `Up: (dir)' +in it. + + The node name `*' is special: it refers to the entire file. Thus, +`g*' shows you the whole current file. The use of the node `*' is to +make it possible to make old-fashioned, unstructured files into nodes +of the tree. + + The `Node:' name, in which a node states its own name, must not +contain a filename, since Info when searching for a node does not expect +one to be there. The `Next', `Previous' and `Up' names may contain +them. In this node, since the `Up' node is in the same file, it was +not necessary to use one. + + Note that the nodes in this file have a file name in the header +line. The file names are ignored by Info, but they serve as comments +to help identify the node for the user. + + +File: info.info, Node: Menus, Next: Cross-refs, Prev: Add, Up: Advanced Info + +2.3 How to Create Menus +======================= + +Any node in the Info hierarchy may have a "menu"--a list of subnodes. +The `m' command searches the current node's menu for the topic which it +reads from the terminal. + + A menu begins with a line starting with `* Menu:'. The rest of the +line is a comment. After the starting line, every line that begins +with a `* ' lists a single topic. The name of the topic-the argument +that the user must give to the `m' command to select this topic--comes +right after the star and space, and is followed by a colon, spaces and +tabs, and the name of the node which discusses that topic. The node +name, like node names following `Next', `Previous' and `Up', may be +terminated with a tab, comma, or newline; it may also be terminated +with a period. + + If the node name and topic name are the same, then rather than +giving the name twice, the abbreviation `* NAME::' may be used (and +should be used, whenever possible, as it reduces the visual clutter in +the menu). + + It is considerate to choose the topic names so that they differ from +each other very near the beginning--this allows the user to type short +abbreviations. In a long menu, it is a good idea to capitalize the +beginning of each item name which is the minimum acceptable +abbreviation for it (a long menu is more than 5 or so entries). + + The nodes listed in a node's menu are called its "subnodes", and it +is their "superior". They should each have an `Up:' pointing at the +superior. It is often useful to arrange all or most of the subnodes in +a sequence of `Next' and `Previous' pointers so that someone who wants +to see them all need not keep revisiting the Menu. + + The Info Directory is simply the menu of the node `(dir)Top'--that +is, node `Top' in file `.../info/dir'. You can put new entries in that +menu just like any other menu. The Info Directory is _not_ the same as +the file directory called `info'. It happens that many of Info's files +live on that file directory, but they do not have to; and files on that +directory are not automatically listed in the Info Directory node. + + Also, although the Info node graph is claimed to be a "hierarchy", +in fact it can be _any_ directed graph. Shared structures and pointer +cycles are perfectly possible, and can be used if they are appropriate +to the meaning to be expressed. There is no need for all the nodes in +a file to form a connected structure. In fact, this file has two +connected components. You are in one of them, which is under the node +`Top'; the other contains the node `Help' which the `h' command goes +to. In fact, since there is no garbage collector, nothing terrible +happens if a substructure is not pointed to, but such a substructure is +rather useless since nobody can ever find out that it exists. + + +File: info.info, Node: Cross-refs, Next: Tags, Prev: Menus, Up: Advanced Info + +2.4 Creating Cross References +============================= + +A cross reference can be placed anywhere in the text, unlike a menu +item which must go at the front of a line. A cross reference looks +like a menu item except that it has `*note' instead of `*'. It +_cannot_ be terminated by a `)', because `)''s are so often part of +node names. If you wish to enclose a cross reference in parentheses, +terminate it with a period first. Here are two examples of cross +references pointers: + + *Note details: commands. (See *note 3: Full Proof.) + + They are just examples. The places they "lead to" do not really +exist! + + +File: info.info, Node: Tags, Next: Checking, Prev: Cross-refs, Up: Advanced Info + +2.5 Tag Tables for Info Files +============================= + +You can speed up the access to nodes of a large Info file by giving it +a tag table. Unlike the tag table for a program, the tag table for an +Info file lives inside the file itself and is used automatically +whenever Info reads in the file. + + To make a tag table, go to a node in the file using Emacs Info mode +and type `M-x Info-tagify'. Then you must use `C-x C-s' to save the +file. + + Once the Info file has a tag table, you must make certain it is up +to date. If, as a result of deletion of text, any node moves back more +than a thousand characters in the file from the position recorded in +the tag table, Info will no longer be able to find that node. To +update the tag table, use the `Info-tagify' command again. + + An Info file tag table appears at the end of the file and looks like +this: + + ^_ + Tag Table: + File: info, Node: Cross-refs^?21419 + File: info, Node: Tags^?22145 + ^_ + End Tag Table + +Note that it contains one line per node, and this line contains the +beginning of the node's header (ending just after the node name), a +Delete character, and the character position in the file of the +beginning of the node. + + +File: info.info, Node: Checking, Next: Emacs Info Variables, Prev: Tags, Up: Advanced Info + +2.6 Checking an Info File +========================= + +When creating an Info file, it is easy to forget the name of a node when +you are making a pointer to it from another node. If you put in the +wrong name for a node, this is not detected until someone tries to go +through the pointer using Info. Verification of the Info file is an +automatic process which checks all pointers to nodes and reports any +pointers which are invalid. Every `Next', `Previous', and `Up' is +checked, as is every menu item and every cross reference. In addition, +any `Next' which does not have a `Previous' pointing back is reported. +Only pointers within the file are checked, because checking pointers to +other files would be terribly slow. But those are usually few. + + To check an Info file, do `M-x Info-validate' while looking at any +node of the file with Emacs Info mode. + + +File: info.info, Node: Emacs Info Variables, Prev: Checking, Up: Advanced Info + +2.7 Emacs Info-mode Variables +============================= + +The following variables may modify the behavior of Info-mode in Emacs; +you may wish to set one or several of these variables interactively, or +in your `~/.emacs' init file. *Note Examining and Setting Variables: +(xemacs)Examining. + +`Info-enable-edit' + Set to `nil', disables the `e' (`Info-edit') command. A non-`nil' + value enables it. *Note Edit: Add. + +`Info-enable-active-nodes' + When set to a non-`nil' value, allows Info to execute Lisp code + associated with nodes. The Lisp code is executed when the node is + selected. + +`Info-directory-list' + The list of directories to search for Info files. Each element is + a string (directory name) or `nil' (try default directory). + +`Info-directory' + The standard directory for Info documentation files. Only used + when the function `Info-directory' is called. + + +File: info.info, Node: Creating an Info File, Prev: Advanced Info, Up: Top + +3 Creating an Info File +*********************** + +*Note Overview of Texinfo: (texinfo)Top, to learn how to write a +Texinfo file. + + *Note Creating an Info File: (texinfo)Create an Info File, to learn +how to create an Info file from a Texinfo file. + + *Note Installing an Info File: (texinfo)Install an Info File, to +learn how to install an Info file after you have created one. + + + +Tag Table: +Node: Top1067 +Node: Getting Started1609 +Node: Help-Small-Screen2358 +Node: Help4112 +Node: Help-P5147 +Node: Help-^L6014 +Node: Help-M8897 +Node: Help-FOO14882 +Node: Help-Adv15630 +Node: Help-Cross18310 +Node: Help-Q18965 +Node: Advanced Info19597 +Node: Expert20576 +Node: Add23095 +Node: Menus26460 +Node: Cross-refs29339 +Node: Tags30046 +Node: Checking31353 +Node: Emacs Info Variables32311 +Node: Creating an Info File33305 + +End Tag Table diff -u -r -N xemacs-21.4.18/info/internals.info xemacs-21.4.19/info/internals.info --- xemacs-21.4.18/info/internals.info 1969-12-31 19:00:00.000000000 -0500 +++ xemacs-21.4.19/info/internals.info 2006-01-28 18:57:51.000000000 -0500 @@ -0,0 +1,196 @@ +This is ../info/internals.info, produced by makeinfo version 4.8 from +internals/internals.texi. + +INFO-DIR-SECTION XEmacs Editor +START-INFO-DIR-ENTRY +* Internals: (internals). XEmacs Internals Manual. +END-INFO-DIR-ENTRY + + Copyright (C) 1992 - 1996 Ben Wing. Copyright (C) 1996, 1997 Sun +Microsystems. Copyright (C) 1994 - 1998, 2002, 2003 Free Software +Foundation. Copyright (C) 1994, 1995 Board of Trustees, University of +Illinois. + + Permission is granted to make and distribute verbatim copies of this +manual provided the copyright notice and this permission notice are +preserved on all copies. + + Permission is granted to copy and distribute modified versions of +this manual under the conditions for verbatim copying, provided that the +entire resulting derived work is distributed under the terms of a +permission notice identical to this one. + + Permission is granted to copy and distribute translations of this +manual into another language, under the above conditions for modified +versions, except that this permission notice may be stated in a +translation approved by the Foundation. + + Permission is granted to copy and distribute modified versions of +this manual under the conditions for verbatim copying, provided also +that the section entitled "GNU General Public License" is included +exactly as in the original, and provided that the entire resulting +derived work is distributed under the terms of a permission notice +identical to this one. + + Permission is granted to copy and distribute translations of this +manual into another language, under the above conditions for modified +versions, except that the section entitled "GNU General Public License" +may be included in a translation approved by the Free Software +Foundation instead of in the original English. + + +Indirect: +internals.info-1: 1789 +internals.info-2: 300999 + +Tag Table: +(Indirect) +Node: Top1789 +Node: A History of Emacs7157 +Node: Through Version 188683 +Node: Lucid Emacs12109 +Node: GNU Emacs 1916158 +Node: GNU Emacs 2018345 +Node: XEmacs18777 +Node: XEmacs From the Outside25894 +Node: The Lisp Language27662 +Node: XEmacs From the Perspective of Building37206 +Node: XEmacs From the Inside43332 +Node: The XEmacs Object System (Abstractly Speaking)51710 +Node: How Lisp Objects Are Represented in C65799 +Node: Rules When Writing New C Code71884 +Node: A Reader's Guide to XEmacs Coding Conventions72784 +Node: General Coding Rules77632 +Node: Writing Lisp Primitives83463 +Node: Writing Good Comments94611 +Node: Adding Global Lisp Variables98155 +Node: Proper Use of Unsigned Types102091 +Node: Coding for Mule103346 +Node: Character-Related Data Types104330 +Node: Working With Character and Byte Positions107312 +Node: Conversion to and from External Data111086 +Node: General Guidelines for Writing Mule-Aware Code117236 +Node: An Example of Mule-Aware Code119933 +Node: Techniques for XEmacs Developers121918 +Node: Regression Testing XEmacs130925 +Node: A Summary of the Various XEmacs Modules135355 +Node: Low-Level Modules136209 +Node: Basic Lisp Modules143632 +Node: Modules for Standard Editing Operations150236 +Node: Editor-Level Control Flow Modules156134 +Node: Modules for the Basic Displayable Lisp Objects159655 +Node: Modules for other Display-Related Lisp Objects162618 +Node: Modules for the Redisplay Mechanism164303 +Node: Modules for Interfacing with the File System166685 +Node: Modules for Other Aspects of the Lisp Interpreter and Object System170393 +Node: Modules for Interfacing with the Operating System178412 +Node: Modules for Interfacing with X Windows185980 +Node: Modules for Internationalization189475 +Node: Modules for Regression Testing192196 +Node: Allocation of Objects in XEmacs Lisp192926 +Node: Introduction to Allocation193453 +Node: Garbage Collection197101 +Node: GCPROing198265 +Node: Garbage Collection - Step by Step205433 +Node: Invocation205835 +Node: garbage_collect_1208817 +Node: mark_object218310 +Node: gc_sweep220133 +Node: sweep_lcrecords_1225208 +Node: compact_string_chars226214 +Node: sweep_strings228405 +Node: sweep_bit_vectors_1229381 +Node: Integers and Characters230068 +Node: Allocation from Frob Blocks230827 +Node: lrecords232438 +Node: Low-level allocation244671 +Node: Cons248785 +Node: Vector249518 +Node: Bit Vector250105 +Node: Symbol250607 +Node: Marker250970 +Node: String251534 +Node: Compiled Function255155 +Node: Dumping255333 +Node: Overview257567 +Node: Data descriptions258128 +Node: Dumping phase260140 +Node: Object inventory260550 +Node: Address allocation263475 +Node: The header264875 +Node: Data dumping265331 +Node: Pointers dumping266003 +Node: Reloading phase267404 +Node: Remaining issues269034 +Node: Events and the Event Loop270002 +Node: Introduction to Events270458 +Node: Main Loop272380 +Node: Specifics of the Event Gathering Mechanism275962 +Node: Specifics About the Emacs Event288423 +Node: The Event Stream Callback Routines288688 +Node: Other Event Loop Functions288943 +Node: Converting Events290090 +Node: Dispatching Events; The Command Builder290706 +Node: Evaluation; Stack Frames; Bindings290948 +Node: Evaluation291296 +Node: Dynamic Binding; The specbinding Stack; Unwind-Protects297815 +Node: Simple Special Forms300209 +Node: Catch and Throw300999 +Node: Symbols and Variables303584 +Node: Introduction to Symbols303854 +Node: Obarrays304899 +Node: Symbol Values308439 +Node: Buffers and Textual Representation310734 +Node: Introduction to Buffers311398 +Node: The Text in a Buffer314068 +Node: Buffer Lists321224 +Node: Markers and Extents323182 +Node: Bufbytes and Emchars325454 +Node: The Buffer Object325676 +Node: MULE Character Sets and Encodings329161 +Node: Character Sets330226 +Node: Encodings333676 +Node: Japanese EUC (Extended Unix Code)334750 +Node: JIS7335575 +Node: Internal Mule Encodings336926 +Node: Internal String Encoding338764 +Node: Internal Character Encoding340889 +Node: CCL342624 +Node: The Lisp Reader and Compiler349302 +Node: Lstreams349518 +Node: Creating an Lstream350552 +Node: Lstream Types351769 +Node: Lstream Functions352032 +Node: Lstream Methods355623 +Node: Consoles; Devices; Frames; Windows358783 +Node: Introduction to Consoles; Devices; Frames; Windows359104 +Node: Point361601 +Node: Window Hierarchy362887 +Node: The Window Object367346 +Node: The Redisplay Mechanism370790 +Node: Critical Redisplay Sections371585 +Node: Line Start Cache372547 +Node: Redisplay Piece by Piece375790 +Node: Extents377834 +Node: Introduction to Extents378374 +Node: Extent Ordering379507 +Node: Format of the Extent Info380755 +Node: Zero-Length Extents382649 +Node: Mathematics of Extent Ordering384055 +Node: Extent Fragments388820 +Node: Faces389913 +Node: Glyphs390032 +Node: Specifiers396699 +Node: Menus396831 +Node: Subprocesses399092 +Node: Interface to the X Window System401081 +Node: Lucid Widget Library401365 +Node: Generic Widget Interface402663 +Node: Scrollbars406223 +Node: Menubars406380 +Node: Checkboxes and Radio Buttons406537 +Node: Progress Bars406737 +Node: Tab Controls406911 +Node: Index407046 + +End Tag Table diff -u -r -N xemacs-21.4.18/info/internals.info-1 xemacs-21.4.19/info/internals.info-1 --- xemacs-21.4.18/info/internals.info-1 1969-12-31 19:00:00.000000000 -0500 +++ xemacs-21.4.19/info/internals.info-1 2006-01-28 18:57:51.000000000 -0500 @@ -0,0 +1,6739 @@ +This is ../info/internals.info, produced by makeinfo version 4.8 from +internals/internals.texi. + +INFO-DIR-SECTION XEmacs Editor +START-INFO-DIR-ENTRY +* Internals: (internals). XEmacs Internals Manual. +END-INFO-DIR-ENTRY + + Copyright (C) 1992 - 1996 Ben Wing. Copyright (C) 1996, 1997 Sun +Microsystems. Copyright (C) 1994 - 1998, 2002, 2003 Free Software +Foundation. Copyright (C) 1994, 1995 Board of Trustees, University of +Illinois. + + Permission is granted to make and distribute verbatim copies of this +manual provided the copyright notice and this permission notice are +preserved on all copies. + + Permission is granted to copy and distribute modified versions of +this manual under the conditions for verbatim copying, provided that the +entire resulting derived work is distributed under the terms of a +permission notice identical to this one. + + Permission is granted to copy and distribute translations of this +manual into another language, under the above conditions for modified +versions, except that this permission notice may be stated in a +translation approved by the Foundation. + + Permission is granted to copy and distribute modified versions of +this manual under the conditions for verbatim copying, provided also +that the section entitled "GNU General Public License" is included +exactly as in the original, and provided that the entire resulting +derived work is distributed under the terms of a permission notice +identical to this one. + + Permission is granted to copy and distribute translations of this +manual into another language, under the above conditions for modified +versions, except that the section entitled "GNU General Public License" +may be included in a translation approved by the Free Software +Foundation instead of in the original English. + + +File: internals.info, Node: Top, Next: A History of Emacs, Prev: (dir), Up: (dir) + + This Info file contains v1.4 of the XEmacs Internals Manual, March +2001. + +* Menu: + +* A History of Emacs:: Times, dates, important events. +* XEmacs From the Outside:: A broad conceptual overview. +* The Lisp Language:: An overview. +* XEmacs From the Perspective of Building:: +* XEmacs From the Inside:: +* The XEmacs Object System (Abstractly Speaking):: +* How Lisp Objects Are Represented in C:: +* Rules When Writing New C Code:: +* Regression Testing XEmacs:: +* A Summary of the Various XEmacs Modules:: +* Allocation of Objects in XEmacs Lisp:: +* Dumping:: +* Events and the Event Loop:: +* Evaluation; Stack Frames; Bindings:: +* Symbols and Variables:: +* Buffers and Textual Representation:: +* MULE Character Sets and Encodings:: +* The Lisp Reader and Compiler:: +* Lstreams:: +* Consoles; Devices; Frames; Windows:: +* The Redisplay Mechanism:: +* Extents:: +* Faces:: +* Glyphs:: +* Specifiers:: +* Menus:: +* Subprocesses:: +* Interface to the X Window System:: +* Index:: + + +--- The Detailed Node Listing --- + +A History of Emacs + +* Through Version 18:: Unification prevails. +* Lucid Emacs:: One version 19 Emacs. +* GNU Emacs 19:: The other version 19 Emacs. +* GNU Emacs 20:: The other version 20 Emacs. +* XEmacs:: The continuation of Lucid Emacs. + +Rules When Writing New C Code + +* General Coding Rules:: +* Writing Lisp Primitives:: +* Adding Global Lisp Variables:: +* Coding for Mule:: +* Techniques for XEmacs Developers:: + +Coding for Mule + +* Character-Related Data Types:: +* Working With Character and Byte Positions:: +* Conversion to and from External Data:: +* General Guidelines for Writing Mule-Aware Code:: +* An Example of Mule-Aware Code:: + +Regression Testing XEmacs + +A Summary of the Various XEmacs Modules + +* Low-Level Modules:: +* Basic Lisp Modules:: +* Modules for Standard Editing Operations:: +* Editor-Level Control Flow Modules:: +* Modules for the Basic Displayable Lisp Objects:: +* Modules for other Display-Related Lisp Objects:: +* Modules for the Redisplay Mechanism:: +* Modules for Interfacing with the File System:: +* Modules for Other Aspects of the Lisp Interpreter and Object System:: +* Modules for Interfacing with the Operating System:: +* Modules for Interfacing with X Windows:: +* Modules for Internationalization:: +* Modules for Regression Testing:: + +Allocation of Objects in XEmacs Lisp + +* Introduction to Allocation:: +* Garbage Collection:: +* GCPROing:: +* Garbage Collection - Step by Step:: +* Integers and Characters:: +* Allocation from Frob Blocks:: +* lrecords:: +* Low-level allocation:: +* Cons:: +* Vector:: +* Bit Vector:: +* Symbol:: +* Marker:: +* String:: +* Compiled Function:: + +Garbage Collection - Step by Step + +* Invocation:: +* garbage_collect_1:: +* mark_object:: +* gc_sweep:: +* sweep_lcrecords_1:: +* compact_string_chars:: +* sweep_strings:: +* sweep_bit_vectors_1:: + +Dumping + +* Overview:: +* Data descriptions:: +* Dumping phase:: +* Reloading phase:: + +Dumping phase + +* Object inventory:: +* Address allocation:: +* The header:: +* Data dumping:: +* Pointers dumping:: + +Events and the Event Loop + +* Introduction to Events:: +* Main Loop:: +* Specifics of the Event Gathering Mechanism:: +* Specifics About the Emacs Event:: +* The Event Stream Callback Routines:: +* Other Event Loop Functions:: +* Converting Events:: +* Dispatching Events; The Command Builder:: + +Evaluation; Stack Frames; Bindings + +* Evaluation:: +* Dynamic Binding; The specbinding Stack; Unwind-Protects:: +* Simple Special Forms:: +* Catch and Throw:: + +Symbols and Variables + +* Introduction to Symbols:: +* Obarrays:: +* Symbol Values:: + +Buffers and Textual Representation + +* Introduction to Buffers:: A buffer holds a block of text such as a file. +* The Text in a Buffer:: Representation of the text in a buffer. +* Buffer Lists:: Keeping track of all buffers. +* Markers and Extents:: Tagging locations within a buffer. +* Bufbytes and Emchars:: Representation of individual characters. +* The Buffer Object:: The Lisp object corresponding to a buffer. + +MULE Character Sets and Encodings + +* Character Sets:: +* Encodings:: +* Internal Mule Encodings:: +* CCL:: + +Encodings + +* Japanese EUC (Extended Unix Code):: +* JIS7:: + +Internal Mule Encodings + +* Internal String Encoding:: +* Internal Character Encoding:: + +Lstreams + +* Creating an Lstream:: Creating an lstream object. +* Lstream Types:: Different sorts of things that are streamed. +* Lstream Functions:: Functions for working with lstreams. +* Lstream Methods:: Creating new lstream types. + +Consoles; Devices; Frames; Windows + +* Introduction to Consoles; Devices; Frames; Windows:: +* Point:: +* Window Hierarchy:: +* The Window Object:: + +The Redisplay Mechanism + +* Critical Redisplay Sections:: +* Line Start Cache:: +* Redisplay Piece by Piece:: + +Extents + +* Introduction to Extents:: Extents are ranges over text, with properties. +* Extent Ordering:: How extents are ordered internally. +* Format of the Extent Info:: The extent information in a buffer or string. +* Zero-Length Extents:: A weird special case. +* Mathematics of Extent Ordering:: A rigorous foundation. +* Extent Fragments:: Cached information useful for redisplay. + + +File: internals.info, Node: A History of Emacs, Next: XEmacs From the Outside, Prev: Top, Up: Top + +1 A History of Emacs +******************** + +XEmacs is a powerful, customizable text editor and development +environment. It began as Lucid Emacs, which was in turn derived from +GNU Emacs, a program written by Richard Stallman of the Free Software +Foundation. GNU Emacs dates back to the 1970's, and was modelled after +a package called "Emacs", written in 1976, that was a set of macros on +top of TECO, an old, old text editor written at MIT on the DEC PDP 10 +under one of the earliest time-sharing operating systems, ITS +(Incompatible Timesharing System). (ITS dates back well before Unix.) +ITS, TECO, and Emacs were products of a group of people at MIT who +called themselves "hackers", who shared an idealistic belief system +about the free exchange of information and were fanatical in their +devotion to and time spent with computers. (The hacker subculture dates +back to the late 1950's at MIT and is described in detail in Steven +Levy's book `Hackers'. This book also includes a lot of information +about Stallman himself and the development of Lisp, a programming +language developed at MIT that underlies Emacs.) + +* Menu: + +* Through Version 18:: Unification prevails. +* Lucid Emacs:: One version 19 Emacs. +* GNU Emacs 19:: The other version 19 Emacs. +* GNU Emacs 20:: The other version 20 Emacs. +* XEmacs:: The continuation of Lucid Emacs. + + +File: internals.info, Node: Through Version 18, Next: Lucid Emacs, Up: A History of Emacs + +1.1 Through Version 18 +====================== + +Although the history of the early versions of GNU Emacs is unclear, the +history is well-known from the middle of 1985. A time line is: + + * GNU Emacs version 15 (15.34) was released sometime in 1984 or 1985 + and shared some code with a version of Emacs written by James + Gosling (the same James Gosling who later created the Java + language). + + * GNU Emacs version 16 (first released version was 16.56) was + released on July 15, 1985. All Gosling code was removed due to + potential copyright problems with the code. + + * version 16.57: released on September 16, 1985. + + * versions 16.58, 16.59: released on September 17, 1985. + + * version 16.60: released on September 19, 1985. These later + version 16's incorporated patches from the net, esp. for getting + Emacs to work under System V. + + * version 17.36 (first official v17 release) released on December 20, + 1985. Included a TeX-able user manual. First official unpatched + version that worked on vanilla System V machines. + + * version 17.43 (second official v17 release) released on January 25, + 1986. + + * version 17.45 released on January 30, 1986. + + * version 17.46 released on February 4, 1986. + + * version 17.48 released on February 10, 1986. + + * version 17.49 released on February 12, 1986. + + * version 17.55 released on March 18, 1986. + + * version 17.57 released on March 27, 1986. + + * version 17.58 released on April 4, 1986. + + * version 17.61 released on April 12, 1986. + + * version 17.63 released on May 7, 1986. + + * version 17.64 released on May 12, 1986. + + * version 18.24 (a beta version) released on October 2, 1986. + + * version 18.30 (a beta version) released on November 15, 1986. + + * version 18.31 (a beta version) released on November 23, 1986. + + * version 18.32 (a beta version) released on December 7, 1986. + + * version 18.33 (a beta version) released on December 12, 1986. + + * version 18.35 (a beta version) released on January 5, 1987. + + * version 18.36 (a beta version) released on January 21, 1987. + + * January 27, 1987: The Great Usenet Renaming. net.emacs is now + comp.emacs. + + * version 18.37 (a beta version) released on February 12, 1987. + + * version 18.38 (a beta version) released on March 3, 1987. + + * version 18.39 (a beta version) released on March 14, 1987. + + * version 18.40 (a beta version) released on March 18, 1987. + + * version 18.41 (the first "official" release) released on March 22, + 1987. + + * version 18.45 released on June 2, 1987. + + * version 18.46 released on June 9, 1987. + + * version 18.47 released on June 18, 1987. + + * version 18.48 released on September 3, 1987. + + * version 18.49 released on September 18, 1987. + + * version 18.50 released on February 13, 1988. + + * version 18.51 released on May 7, 1988. + + * version 18.52 released on September 1, 1988. + + * version 18.53 released on February 24, 1989. + + * version 18.54 released on April 26, 1989. + + * version 18.55 released on August 23, 1989. This is the earliest + version that is still available by FTP. + + * version 18.56 released on January 17, 1991. + + * version 18.57 released late January, 1991. + + * version 18.58 released ?????. + + * version 18.59 released October 31, 1992. + + +File: internals.info, Node: Lucid Emacs, Next: GNU Emacs 19, Prev: Through Version 18, Up: A History of Emacs + +1.2 Lucid Emacs +=============== + +Lucid Emacs was developed by the (now-defunct) Lucid Inc., a maker of +C++ and Lisp development environments. It began when Lucid decided they +wanted to use Emacs as the editor and cornerstone of their C++ +development environment (called "Energize"). They needed many features +that were not available in the existing version of GNU Emacs (version +18.5something), in particular good and integrated support for GUI +elements such as mouse support, multiple fonts, multiple window-system +windows, etc. A branch of GNU Emacs called Epoch, written at the +University of Illinois, existed that supplied many of these features; +however, Lucid needed more than what existed in Epoch. At the time, the +Free Software Foundation was working on version 19 of Emacs (this was +sometime around 1991), which was planned to have similar features, and +so Lucid decided to work with the Free Software Foundation. Their plan +was to add features that they needed, and coordinate with the FSF so +that the features would get included back into Emacs version 19. + + Delays in the release of version 19 occurred, however (resulting in +it finally being released more than a year after what was initially +planned), and Lucid encountered unexpected technical resistance in +getting their changes merged back into version 19, so they decided to +release their own version of Emacs, which became Lucid Emacs 19.0. + + The initial authors of Lucid Emacs were Matthieu Devin, Harlan +Sexton, and Eric Benson, and the work was later taken over by Jamie +Zawinski, who became "Mr. Lucid Emacs" for many releases. + + A time line for Lucid Emacs is + + * version 19.0 shipped with Energize 1.0, April 1992. + + * version 19.1 released June 4, 1992. + + * version 19.2 released June 19, 1992. + + * version 19.3 released September 9, 1992. + + * version 19.4 released January 21, 1993. + + * version 19.5 was a repackaging of 19.4 with a few bug fixes and + shipped with Energize 2.0. Never released to the net. + + * version 19.6 released April 9, 1993. + + * version 19.7 was a repackaging of 19.6 with a few bug fixes and + shipped with Energize 2.1. Never released to the net. + + * version 19.8 released September 6, 1993. + + * version 19.9 released January 12, 1994. + + * version 19.10 released May 27, 1994. + + * version 19.11 (first XEmacs) released September 13, 1994. + + * version 19.12 released June 23, 1995. + + * version 19.13 released September 1, 1995. + + * version 19.14 released June 23, 1996. + + * version 20.0 released February 9, 1997. + + * version 19.15 released March 28, 1997. + + * version 20.1 (not released to the net) April 15, 1997. + + * version 20.2 released May 16, 1997. + + * version 19.16 released October 31, 1997. + + * version 20.3 (the first stable version of XEmacs 20.x) released + November 30, 1997. + + * version 20.4 released February 28, 1998. + + * version 21.1.2 released May 14, 1999. (The version naming scheme + was changed at this point: [a] the second version number is odd + for stable versions, even for beta versions; [b] a third version + number is added, replacing the "beta xxx" ending for beta versions + and allowing for periodic maintenance releases for stable + versions. Therefore, 21.0 was never "officially" released; + similarly for 21.2, etc.) + + * version 21.1.3 released June 26, 1999. + + * version 21.1.4 released July 8, 1999. + + * version 21.1.6 released August 14, 1999. (There was no 21.1.5.) + + * version 21.1.7 released September 26, 1999. + + * version 21.1.8 released November 2, 1999. + + * version 21.1.9 released February 13, 2000. + + * version 21.1.10 released May 7, 2000. + + * version 21.1.10a released June 24, 2000. + + * version 21.1.11 released July 18, 2000. + + * version 21.1.12 released August 5, 2000. + + * version 21.1.13 released January 7, 2001. + + * version 21.1.14 released January 27, 2001. + + +File: internals.info, Node: GNU Emacs 19, Next: GNU Emacs 20, Prev: Lucid Emacs, Up: A History of Emacs + +1.3 GNU Emacs 19 +================ + +About a year after the initial release of Lucid Emacs, the FSF released +a beta of their version of Emacs 19 (referred to here as "GNU Emacs"). +By this time, the current version of Lucid Emacs was 19.6. (Strangely, +the first released beta from the FSF was GNU Emacs 19.7.) A time line +for GNU Emacs version 19 is + + * version 19.8 (beta) released May 27, 1993. + + * version 19.9 (beta) released May 27, 1993. + + * version 19.10 (beta) released May 30, 1993. + + * version 19.11 (beta) released June 1, 1993. + + * version 19.12 (beta) released June 2, 1993. + + * version 19.13 (beta) released June 8, 1993. + + * version 19.14 (beta) released June 17, 1993. + + * version 19.15 (beta) released June 19, 1993. + + * version 19.16 (beta) released July 6, 1993. + + * version 19.17 (beta) released late July, 1993. + + * version 19.18 (beta) released August 9, 1993. + + * version 19.19 (beta) released August 15, 1993. + + * version 19.20 (beta) released November 17, 1993. + + * version 19.21 (beta) released November 17, 1993. + + * version 19.22 (beta) released November 28, 1993. + + * version 19.23 (beta) released May 17, 1994. + + * version 19.24 (beta) released May 16, 1994. + + * version 19.25 (beta) released June 3, 1994. + + * version 19.26 (beta) released September 11, 1994. + + * version 19.27 (beta) released September 14, 1994. + + * version 19.28 (first "official" release) released November 1, 1994. + + * version 19.29 released June 21, 1995. + + * version 19.30 released November 24, 1995. + + * version 19.31 released May 25, 1996. + + * version 19.32 released July 31, 1996. + + * version 19.33 released August 11, 1996. + + * version 19.34 released August 21, 1996. + + * version 19.34b released September 6, 1996. + + In some ways, GNU Emacs 19 was better than Lucid Emacs; in some ways, +worse. Lucid soon began incorporating features from GNU Emacs 19 into +Lucid Emacs; the work was mostly done by Richard Mlynarik, who had been +working on and using GNU Emacs for a long time (back as far as version +16 or 17). + + +File: internals.info, Node: GNU Emacs 20, Next: XEmacs, Prev: GNU Emacs 19, Up: A History of Emacs + +1.4 GNU Emacs 20 +================ + +On February 2, 1997 work began on GNU Emacs to integrate Mule. The +first release was made in September of that year. + + A timeline for Emacs 20 is + + * version 20.1 released September 17, 1997. + + * version 20.2 released September 20, 1997. + + * version 20.3 released August 19, 1998. + + +File: internals.info, Node: XEmacs, Prev: GNU Emacs 20, Up: A History of Emacs + +1.5 XEmacs +========== + +Around the time that Lucid was developing Energize, Sun Microsystems +was developing their own development environment (called "SPARCWorks") +and also decided to use Emacs. They joined forces with the Epoch team +at the University of Illinois and later with Lucid. The maintainer of +the last-released version of Epoch was Marc Andreessen, but he dropped +out and the Epoch project, headed by Simon Kaplan, lured Chuck Thompson +away from a system administration job to become the primary Lucid Emacs +author for Epoch and Sun. Chuck's area of specialty became the +redisplay engine (he replaced the old Lucid Emacs redisplay engine with +a ported version from Epoch and then later rewrote it from scratch). +Sun also hired Ben Wing (the author of Win-Emacs, a port of Lucid Emacs +to Microsoft Windows 3.1) in 1993, for what was initially a one-month +contract to fix some event problems but later became a many-year +involvement, punctuated by a six-month contract with Amdahl Corporation. + + In 1994, Sun and Lucid agreed to rename Lucid Emacs to XEmacs (a name +not favorable to either company); the first release called XEmacs was +version 19.11. In June 1994, Lucid folded and Jamie quit to work for +the newly formed Mosaic Communications Corp., later Netscape +Communications Corp. (co-founded by the same Marc Andreessen, who had +quit his Epoch job to work on a graphical browser for the World Wide +Web). Chuck then become the primary maintainer of XEmacs, and put out +versions 19.11 through 19.14 in conjunction with Ben. For 19.12 and +19.13, Chuck added the new redisplay and many other display improvements +and Ben added MULE support (support for Asian and other languages) and +redesigned most of the internal Lisp subsystems to better support the +MULE work and the various other features being added to XEmacs. After +19.14 Chuck retired as primary maintainer and Steve Baur stepped in. + + Soon after 19.13 was released, work began in earnest on the MULE +internationalization code and the source tree was divided into two +development paths. The MULE version was initially called 19.20, but was +soon renamed to 20.0. In 1996 Martin Buchholz of Sun Microsystems took +over the care and feeding of it and worked on it in parallel with the +19.14 development that was occurring at the same time. After much work +by Martin, it was decided to release 20.0 ahead of 19.15 in February +1997. The source tree remained divided until 20.2 when the version 19 +source was finally retired at version 19.16. + + In 1997, Sun finally dropped all pretense of support for XEmacs and +Martin Buchholz left the company in November. Since then, and mostly +for the previous year, because Steve Baur was never paid to work on +XEmacs, XEmacs has existed solely on the contributions of volunteers +from the Free Software Community. Starting from 1997, Hrvoje Niksic and +Kyle Jones have figured prominently in XEmacs development. + + Many attempts have been made to merge XEmacs and GNU Emacs, but they +have consistently failed. + + A more detailed history is contained in the XEmacs About page. + + A time line for XEmacs is + + * version 19.11 (first XEmacs) released September 13, 1994. + + * version 19.12 released June 23, 1995. + + * version 19.13 released September 1, 1995. + + * version 19.14 released June 23, 1996. + + * version 20.0 released February 9, 1997. + + * version 19.15 released March 28, 1997. + + * version 20.1 (not released to the net) April 15, 1997. + + * version 20.2 released May 16, 1997. + + * version 19.16 released October 31, 1997. + + * version 20.3 (the first stable version of XEmacs 20.x) released + November 30, 1997. + + * version 20.4 released February 28, 1998. + + * version 21.0.60 released December 10, 1998. (The version naming + scheme was changed at this point: [a] the second version number is + odd for stable versions, even for beta versions; [b] a third + version number is added, replacing the "beta xxx" ending for beta + versions and allowing for periodic maintenance releases for stable + versions. Therefore, 21.0 was never "officially" released; + similarly for 21.2, etc.) + + * version 21.0.61 released January 4, 1999. + + * version 21.0.63 released February 3, 1999. + + * version 21.0.64 released March 1, 1999. + + * version 21.0.65 released March 5, 1999. + + * version 21.0.66 released March 12, 1999. + + * version 21.0.67 released March 25, 1999. + + * version 21.1.2 released May 14, 1999. (This is the followup to + 21.0.67. The second version number was bumped to indicate the + beginning of the "stable" series.) + + * version 21.1.3 released June 26, 1999. + + * version 21.1.4 released July 8, 1999. + + * version 21.1.6 released August 14, 1999. (There was no 21.1.5.) + + * version 21.1.7 released September 26, 1999. + + * version 21.1.8 released November 2, 1999. + + * version 21.1.9 released February 13, 2000. + + * version 21.1.10 released May 7, 2000. + + * version 21.1.10a released June 24, 2000. + + * version 21.1.11 released July 18, 2000. + + * version 21.1.12 released August 5, 2000. + + * version 21.1.13 released January 7, 2001. + + * version 21.1.14 released January 27, 2001. + + * version 21.2.9 released February 3, 1999. + + * version 21.2.10 released February 5, 1999. + + * version 21.2.11 released March 1, 1999. + + * version 21.2.12 released March 5, 1999. + + * version 21.2.13 released March 12, 1999. + + * version 21.2.14 released May 14, 1999. + + * version 21.2.15 released June 4, 1999. + + * version 21.2.16 released June 11, 1999. + + * version 21.2.17 released June 22, 1999. + + * version 21.2.18 released July 14, 1999. + + * version 21.2.19 released July 30, 1999. + + * version 21.2.20 released November 10, 1999. + + * version 21.2.21 released November 28, 1999. + + * version 21.2.22 released November 29, 1999. + + * version 21.2.23 released December 7, 1999. + + * version 21.2.24 released December 14, 1999. + + * version 21.2.25 released December 24, 1999. + + * version 21.2.26 released December 31, 1999. + + * version 21.2.27 released January 18, 2000. + + * version 21.2.28 released February 7, 2000. + + * version 21.2.29 released February 16, 2000. + + * version 21.2.30 released February 21, 2000. + + * version 21.2.31 released February 23, 2000. + + * version 21.2.32 released March 20, 2000. + + * version 21.2.33 released May 1, 2000. + + * version 21.2.34 released May 28, 2000. + + * version 21.2.35 released July 19, 2000. + + * version 21.2.36 released October 4, 2000. + + * version 21.2.37 released November 14, 2000. + + * version 21.2.38 released December 5, 2000. + + * version 21.2.39 released December 31, 2000. + + * version 21.2.40 released January 8, 2001. + + * version 21.2.41 released January 17, 2001. + + * version 21.2.42 released January 20, 2001. + + * version 21.2.43 released January 26, 2001. + + * version 21.2.44 released February 8, 2001. + + * version 21.2.45 released February 23, 2001. + + * version 21.2.46 released March 21, 2001. + + +File: internals.info, Node: XEmacs From the Outside, Next: The Lisp Language, Prev: A History of Emacs, Up: Top + +2 XEmacs From the Outside +************************* + +XEmacs appears to the outside world as an editor, but it is really a +Lisp environment. At its heart is a Lisp interpreter; it also +"happens" to contain many specialized object types (e.g. buffers, +windows, frames, events) that are useful for implementing an editor. +Some of these objects (in particular windows and frames) have +displayable representations, and XEmacs provides a function +`redisplay()' that ensures that the display of all such objects matches +their internal state. Most of the time, a standard Lisp environment is +in a "read-eval-print" loop--i.e. "read some Lisp code, execute it, and +print the results". XEmacs has a similar loop: + + * read an event + + * dispatch the event (i.e. "do it") + + * redisplay + + Reading an event is done using the Lisp function `next-event', which +waits for something to happen (typically, the user presses a key or +moves the mouse) and returns an event object describing this. +Dispatching an event is done using the Lisp function `dispatch-event', +which looks up the event in a keymap object (a particular kind of +object that associates an event with a Lisp function) and calls that +function. The function "does" what the user has requested by changing +the state of particular frame objects, buffer objects, etc. Finally, +`redisplay()' is called, which updates the display to reflect those +changes just made. Thus is an "editor" born. + + Note that you do not have to use XEmacs as an editor; you could just +as well make it do your taxes, compute pi, play bridge, etc. You'd just +have to write functions to do those operations in Lisp. + + +File: internals.info, Node: The Lisp Language, Next: XEmacs From the Perspective of Building, Prev: XEmacs From the Outside, Up: Top + +3 The Lisp Language +******************* + +Lisp is a general-purpose language that is higher-level than C and in +many ways more powerful than C. Powerful dialects of Lisp such as +Common Lisp are probably much better languages for writing very large +applications than is C. (Unfortunately, for many non-technical reasons +C and its successor C++ have become the dominant languages for +application development. These languages are both inadequate for +extremely large applications, which is evidenced by the fact that newer, +larger programs are becoming ever harder to write and are requiring ever +more programmers despite great increases in C development environments; +and by the fact that, although hardware speeds and reliability have been +growing at an exponential rate, most software is still generally +considered to be slow and buggy.) + + The new Java language holds promise as a better general-purpose +development language than C. Java has many features in common with +Lisp that are not shared by C (this is not a coincidence, since Java +was designed by James Gosling, a former Lisp hacker). This will be +discussed more later. + + For those used to C, here is a summary of the basic differences +between C and Lisp: + + 1. Lisp has an extremely regular syntax. Every function, expression, + and control statement is written in the form + + (FUNC ARG1 ARG2 ...) + + This is as opposed to C, which writes functions as + + func(ARG1, ARG2, ...) + + but writes expressions involving operators as (e.g.) + + ARG1 + ARG2 + + and writes control statements as (e.g.) + + while (EXPR) { STATEMENT1; STATEMENT2; ... } + + Lisp equivalents of the latter two would be + + (+ ARG1 ARG2 ...) + + and + + (while EXPR STATEMENT1 STATEMENT2 ...) + + 2. Lisp is a safe language. Assuming there are no bugs in the Lisp + interpreter/compiler, it is impossible to write a program that + "core dumps" or otherwise causes the machine to execute an illegal + instruction. This is very different from C, where perhaps the most + common outcome of a bug is exactly such a crash. A corollary of + this is that the C operation of casting a pointer is impossible + (and unnecessary) in Lisp, and that it is impossible to access + memory outside the bounds of an array. + + 3. Programs and data are written in the same form. The + parenthesis-enclosing form described above for statements is the + same form used for the most common data type in Lisp, the list. + Thus, it is possible to represent any Lisp program using Lisp data + types, and for one program to construct Lisp statements and then + dynamically "evaluate" them, or cause them to execute. + + 4. All objects are "dynamically typed". This means that part of every + object is an indication of what type it is. A Lisp program can + manipulate an object without knowing what type it is, and can + query an object to determine its type. This means that, + correspondingly, variables and function parameters can hold + objects of any type and are not normally declared as being of any + particular type. This is opposed to the "static typing" of C, + where variables can hold exactly one type of object and must be + declared as such, and objects do not contain an indication of + their type because it's implicit in the variables they are stored + in. It is possible in C to have a variable hold different types + of objects (e.g. through the use of `void *' pointers or + variable-argument functions), but the type information must then be + passed explicitly in some other fashion, leading to additional + program complexity. + + 5. Allocated memory is automatically reclaimed when it is no longer + in use. This operation is called "garbage collection" and + involves looking through all variables to see what memory is being + pointed to, and reclaiming any memory that is not pointed to and + is thus "inaccessible" and out of use. This is as opposed to C, + in which allocated memory must be explicitly reclaimed using + `free()'. If you simply drop all pointers to memory without + freeing it, it becomes "leaked" memory that still takes up space. + Over a long period of time, this can cause your program to grow + and grow until it runs out of memory. + + 6. Lisp has built-in facilities for handling errors and exceptions. + In C, when an error occurs, usually either the program exits + entirely or the routine in which the error occurs returns a value + indicating this. If an error occurs in a deeply-nested routine, + then every routine currently called must unwind itself normally + and return an error value back up to the next routine. This means + that every routine must explicitly check for an error in all the + routines it calls; if it does not do so, unexpected and often + random behavior results. This is an extremely common source of + bugs in C programs. An alternative would be to do a non-local + exit using `longjmp()', but that is often very dangerous because + the routines that were exited past had no opportunity to clean up + after themselves and may leave things in an inconsistent state, + causing a crash shortly afterwards. + + Lisp provides mechanisms to make such non-local exits safe. When + an error occurs, a routine simply signals that an error of a + particular class has occurred, and a non-local exit takes place. + Any routine can trap errors occurring in routines it calls by + registering an error handler for some or all classes of errors. + (If no handler is registered, a default handler, generally + installed by the top-level event loop, is executed; this prints + out the error and continues.) Routines can also specify cleanup + code (called an "unwind-protect") that will be called when control + exits from a block of code, no matter how that exit occurs--i.e. + even if a function deeply nested below it causes a non-local exit + back to the top level. + + Note that this facility has appeared in some recent vintages of C, + in particular Visual C++ and other PC compilers written for the + Microsoft Win32 API. + + 7. In Emacs Lisp, local variables are "dynamically scoped". This + means that if you declare a local variable in a particular + function, and then call another function, that subfunction can + "see" the local variable you declared. This is actually + considered a bug in Emacs Lisp and in all other early dialects of + Lisp, and was corrected in Common Lisp. (In Common Lisp, you can + still declare dynamically scoped variables if you want to--they + are sometimes useful--but variables by default are "lexically + scoped" as in C.) + + For those familiar with Lisp, Emacs Lisp is modelled after MacLisp, +an early dialect of Lisp developed at MIT (no relation to the Macintosh +computer). There is a Common Lisp compatibility package available for +Emacs that provides many of the features of Common Lisp. + + The Java language is derived in many ways from C, and shares a +similar syntax, but has the following features in common with Lisp (and +different from C): + + 1. Java is a safe language, like Lisp. + + 2. Java provides garbage collection, like Lisp. + + 3. Java has built-in facilities for handling errors and exceptions, + like Lisp. + + 4. Java has a type system that combines the best advantages of both + static and dynamic typing. Objects (except very simple types) are + explicitly marked with their type, as in dynamic typing; but there + is a hierarchy of types and functions are declared to accept only + certain types, thus providing the increased compile-time + error-checking of static typing. + + The Java language also has some negative attributes: + + 1. Java uses the edit/compile/run model of software development. This + makes it hard to use interactively. For example, to use Java like + `bc' it is necessary to write a special purpose, albeit tiny, + application. In Emacs Lisp, a calculator comes built-in without + any effort - one can always just type an expression in the + `*scratch*' buffer. + + 2. Java tries too hard to enforce, not merely enable, portability, + making ordinary access to standard OS facilities painful. Java + has an "agenda". I think this is why `chdir' is not part of + standard Java, which is inexcusable. + + Unfortunately, there is no perfect language. Static typing allows a +compiler to catch programmer errors and produce more efficient code, but +makes programming more tedious and less fun. For the foreseeable +future, an Ideal Editing and Programming Environment (and that is what +XEmacs aspires to) will be programmable in multiple languages: high +level ones like Lisp for user customization and prototyping, and lower +level ones for infrastructure and industrial strength applications. If +I had my way, XEmacs would be friendly towards the Python, Scheme, C++, +ML, etc... communities. But there are serious technical difficulties to +achieving that goal. + + The word "application" in the previous paragraph was used +intentionally. XEmacs implements an API for programs written in Lisp +that makes it a full-fledged application platform, very much like an OS +inside the real OS. + + +File: internals.info, Node: XEmacs From the Perspective of Building, Next: XEmacs From the Inside, Prev: The Lisp Language, Up: Top + +4 XEmacs From the Perspective of Building +***************************************** + +The heart of XEmacs is the Lisp environment, which is written in C. +This is contained in the `src/' subdirectory. Underneath `src/' are +two subdirectories of header files: `s/' (header files for particular +operating systems) and `m/' (header files for particular machine +types). In practice the distinction between the two types of header +files is blurred. These header files define or undefine certain +preprocessor constants and macros to indicate particular +characteristics of the associated machine or operating system. As part +of the configure process, one `s/' file and one `m/' file is identified +for the particular environment in which XEmacs is being built. + + XEmacs also contains a great deal of Lisp code. This implements the +operations that make XEmacs useful as an editor as well as just a Lisp +environment, and also contains many add-on packages that allow XEmacs to +browse directories, act as a mail and Usenet news reader, compile Lisp +code, etc. There is actually more Lisp code than C code associated with +XEmacs, but much of the Lisp code is peripheral to the actual operation +of the editor. The Lisp code all lies in subdirectories underneath the +`lisp/' directory. + + The `lwlib/' directory contains C code that implements a generalized +interface onto different X widget toolkits and also implements some +widgets of its own that behave like Motif widgets but are faster, free, +and in some cases more powerful. The code in this directory compiles +into a library and is mostly independent from XEmacs. + + The `etc/' directory contains various data files associated with +XEmacs. Some of them are actually read by XEmacs at startup; others +merely contain useful information of various sorts. + + The `lib-src/' directory contains C code for various auxiliary +programs that are used in connection with XEmacs. Some of them are used +during the build process; others are used to perform certain functions +that cannot conveniently be placed in the XEmacs executable (e.g. the +`movemail' program for fetching mail out of `/var/spool/mail', which +must be setgid to `mail' on many systems; and the `gnuclient' program, +which allows an external script to communicate with a running XEmacs +process). + + The `man/' directory contains the sources for the XEmacs +documentation. It is mostly in a form called Texinfo, which can be +converted into either a printed document (by passing it through TeX) or +into on-line documentation called "info files". + + The `info/' directory contains the results of formatting the XEmacs +documentation as "info files", for on-line use. These files are used +when you enter the Info system using `C-h i' or through the Help menu. + + The `dynodump/' directory contains auxiliary code used to build +XEmacs on Solaris platforms. + + The other directories contain various miscellaneous code and +information that is not normally used or needed. + + The first step of building involves running the `configure' program +and passing it various parameters to specify any optional features you +want and compiler arguments and such, as described in the `INSTALL' +file. This determines what the build environment is, chooses the +appropriate `s/' and `m/' file, and runs a series of tests to determine +many details about your environment, such as which library functions +are available and exactly how they work. The reason for running these +tests is that it allows XEmacs to be compiled on a much wider variety +of platforms than those that the XEmacs developers happen to be +familiar with, including various sorts of hybrid platforms. This is +especially important now that many operating systems give you a great +deal of control over exactly what features you want installed, and allow +for easy upgrading of parts of a system without upgrading the rest. It +would be impossible to pre-determine and pre-specify the information for +all possible configurations. + + In fact, the `s/' and `m/' files are basically _evil_, since they +contain unmaintainable platform-specific hard-coded information. +XEmacs has been moving in the direction of having all system-specific +information be determined dynamically by `configure'. Perhaps someday +we can `rm -rf src/s src/m'. + + When configure is done running, it generates `Makefile's and +`GNUmakefile's and the file `src/config.h' (which describes the +features of your system) from template files. You then run `make', +which compiles the auxiliary code and programs in `lib-src/' and +`lwlib/' and the main XEmacs executable in `src/'. The result of +compiling and linking is an executable called `temacs', which is _not_ +the final XEmacs executable. `temacs' by itself is not intended to +function as an editor or even display any windows on the screen, and if +you simply run it, it will exit immediately. The `Makefile' runs +`temacs' with certain options that cause it to initialize itself, read +in a number of basic Lisp files, and then dump itself out into a new +executable called `xemacs'. This new executable has been +pre-initialized and contains pre-digested Lisp code that is necessary +for the editor to function (this includes most basic editing functions, +e.g. `kill-line', that can be defined in terms of other Lisp +primitives; some initialization code that is called when certain +objects, such as frames, are created; and all of the standard +keybindings and code for the actions they result in). This executable, +`xemacs', is the executable that you run to use the XEmacs editor. + + Although `temacs' is not intended to be run as an editor, it can, by +using the incantation `temacs -batch -l loadup.el run-temacs'. This is +useful when the dumping procedure described above is broken, or when +using certain program debugging tools such as Purify. These tools get +mighty confused by the tricks played by the XEmacs build process, such +as allocation memory in one process, and freeing it in the next. + + +File: internals.info, Node: XEmacs From the Inside, Next: The XEmacs Object System (Abstractly Speaking), Prev: XEmacs From the Perspective of Building, Up: Top + +5 XEmacs From the Inside +************************ + +Internally, XEmacs is quite complex, and can be very confusing. To +simplify things, it can be useful to think of XEmacs as containing an +event loop that "drives" everything, and a number of other subsystems, +such as a Lisp engine and a redisplay mechanism. Each of these other +subsystems exists simultaneously in XEmacs, and each has a certain +state. The flow of control continually passes in and out of these +different subsystems in the course of normal operation of the editor. + + It is important to keep in mind that, most of the time, the editor is +"driven" by the event loop. Except during initialization and batch +mode, all subsystems are entered directly or indirectly through the +event loop, and ultimately, control exits out of all subsystems back up +to the event loop. This cycle of entering a subsystem, exiting back out +to the event loop, and starting another iteration of the event loop +occurs once each keystroke, mouse motion, etc. + + If you're trying to understand a particular subsystem (other than the +event loop), think of it as a "daemon" process or "servant" that is +responsible for one particular aspect of a larger system, and +periodically receives commands or environment changes that cause it to +do something. Ultimately, these commands and environment changes are +always triggered by the event loop. For example: + + * The window and frame mechanism is responsible for keeping track of + what windows and frames exist, what buffers are in them, etc. It + is periodically given commands (usually from the user) to make a + change to the current window/frame state: i.e. create a new frame, + delete a window, etc. + + * The buffer mechanism is responsible for keeping track of what + buffers exist and what text is in them. It is periodically given + commands (usually from the user) to insert or delete text, create + a buffer, etc. When it receives a text-change command, it + notifies the redisplay mechanism. + + * The redisplay mechanism is responsible for making sure that + windows and frames are displayed correctly. It is periodically + told (by the event loop) to actually "do its job", i.e. snoop + around and see what the current state of the environment (mostly + of the currently-existing windows, frames, and buffers) is, and + make sure that state matches what's actually displayed. It keeps + lots and lots of information around (such as what is actually + being displayed currently, and what the environment was last time + it checked) so that it can minimize the work it has to do. It is + also helped along in that whenever a relevant change to the + environment occurs, the redisplay mechanism is told about this, so + it has a pretty good idea of where it has to look to find possible + changes and doesn't have to look everywhere. + + * The Lisp engine is responsible for executing the Lisp code in + which most user commands are written. It is entered through a + call to `eval' or `funcall', which occurs as a result of + dispatching an event from the event loop. The functions it calls + issue commands to the buffer mechanism, the window/frame + subsystem, etc. + + * The Lisp allocation subsystem is responsible for keeping track of + Lisp objects. It is given commands from the Lisp engine to + allocate objects, garbage collect, etc. + + etc. + + The important idea here is that there are a number of independent +subsystems each with its own responsibility and persistent state, just +like different employees in a company, and each subsystem is +periodically given commands from other subsystems. Commands can flow +from any one subsystem to any other, but there is usually some sort of +hierarchy, with all commands originating from the event subsystem. + + XEmacs is entered in `main()', which is in `emacs.c'. When this is +called the first time (in a properly-invoked `temacs'), it does the +following: + + 1. It does some very basic environment initializations, such as + determining where it and its directories (e.g. `lisp/' and `etc/') + reside and setting up signal handlers. + + 2. It initializes the entire Lisp interpreter. + + 3. It sets the initial values of many built-in variables (including + many variables that are visible to Lisp programs), such as the + global keymap object and the built-in faces (a face is an object + that describes the display characteristics of text). This + involves creating Lisp objects and thus is dependent on step (2). + + 4. It performs various other initializations that are relevant to the + particular environment it is running in, such as retrieving + environment variables, determining the current date and the user + who is running the program, examining its standard input, creating + any necessary file descriptors, etc. + + 5. At this point, the C initialization is complete. A Lisp program + that was specified on the command line (usually `loadup.el') is + called (temacs is normally invoked as `temacs -batch -l loadup.el + dump'). `loadup.el' loads all of the other Lisp files that are + needed for the operation of the editor, calls the `dump-emacs' + function to write out `xemacs', and then kills the temacs process. + + When `xemacs' is then run, it only redoes steps (1) and (4) above; +all variables already contain the values they were set to when the +executable was dumped, and all memory that was allocated with +`malloc()' is still around. (XEmacs knows whether it is being run as +`xemacs' or `temacs' because it sets the global variable `initialized' +to 1 after step (4) above.) At this point, `xemacs' calls a Lisp +function to do any further initialization, which includes parsing the +command-line (the C code can only do limited command-line parsing, +which includes looking for the `-batch' and `-l' flags and a few other +flags that it needs to know about before initialization is complete), +creating the first frame (or "window" in standard window-system +parlance), running the user's init file (usually the file `.emacs' in +the user's home directory), etc. The function to do this is usually +called `normal-top-level'; `loadup.el' tells the C code about this +function by setting its name as the value of the Lisp variable +`top-level'. + + When the Lisp initialization code is done, the C code enters the +event loop, and stays there for the duration of the XEmacs process. +The code for the event loop is contained in `cmdloop.c', and is called +`Fcommand_loop_1()'. Note that this event loop could very well be +written in Lisp, and in fact a Lisp version exists; but apparently, +doing this makes XEmacs run noticeably slower. + + Notice how much of the initialization is done in Lisp, not in C. In +general, XEmacs tries to move as much code as is possible into Lisp. +Code that remains in C is code that implements the Lisp interpreter +itself, or code that needs to be very fast, or code that needs to do +system calls or other such stuff that needs to be done in C, or code +that needs to have access to "forbidden" structures. (One conscious +aspect of the design of Lisp under XEmacs is a clean separation between +the external interface to a Lisp object's functionality and its internal +implementation. Part of this design is that Lisp programs are +forbidden from accessing the contents of the object other than through +using a standard API. In this respect, XEmacs Lisp is similar to +modern Lisp dialects but differs from GNU Emacs, which tends to expose +the implementation and allow Lisp programs to look at it directly. The +major advantage of hiding the implementation is that it allows the +implementation to be redesigned without affecting any Lisp programs, +including those that might want to be "clever" by looking directly at +the object's contents and possibly manipulating them.) + + Moving code into Lisp makes the code easier to debug and maintain and +makes it much easier for people who are not XEmacs developers to +customize XEmacs, because they can make a change with much less chance +of obscure and unwanted interactions occurring than if they were to +change the C code. + + +File: internals.info, Node: The XEmacs Object System (Abstractly Speaking), Next: How Lisp Objects Are Represented in C, Prev: XEmacs From the Inside, Up: Top + +6 The XEmacs Object System (Abstractly Speaking) +************************************************ + +At the heart of the Lisp interpreter is its management of objects. +XEmacs Lisp contains many built-in objects, some of which are simple +and others of which can be very complex; and some of which are very +common, and others of which are rarely used or are only used +internally. (Since the Lisp allocation system, with its automatic +reclamation of unused storage, is so much more convenient than +`malloc()' and `free()', the C code makes extensive use of it in its +internal operations.) + + The basic Lisp objects are + +`integer' + 28 or 31 bits of precision, or 60 or 63 bits on 64-bit machines; + the reason for this is described below when the internal Lisp + object representation is described. + +`float' + Same precision as a double in C. + +`cons' + A simple container for two Lisp objects, used to implement lists + and most other data structures in Lisp. + +`char' + An object representing a single character of text; chars behave + like integers in many ways but are logically considered text + rather than numbers and have a different read syntax. (the read + syntax for a char contains the char itself or some textual + encoding of it--for example, a Japanese Kanji character might be + encoded as `^[$(B#&^[(B' using the ISO-2022 encoding + standard--rather than the numerical representation of the char; + this way, if the mapping between chars and integers changes, which + is quite possible for Kanji characters and other extended + characters, the same character will still be created. Note that + some primitives confuse chars and integers. The worst culprit is + `eq', which makes a special exception and considers a char to be + `eq' to its integer equivalent, even though in no other case are + objects of two different types `eq'. The reason for this + monstrosity is compatibility with existing code; the separation of + char from integer came fairly recently.) + +`symbol' + An object that contains Lisp objects and is referred to by name; + symbols are used to implement variables and named functions and to + provide the equivalent of preprocessor constants in C. + +`vector' + A one-dimensional array of Lisp objects providing constant-time + access to any of the objects; access to an arbitrary object in a + vector is faster than for lists, but the operations that can be + done on a vector are more limited. + +`string' + Self-explanatory; behaves much like a vector of chars but has a + different read syntax and is stored and manipulated more compactly. + +`bit-vector' + A vector of bits; similar to a string in spirit. + +`compiled-function' + An object containing compiled Lisp code, known as "byte code". + +`subr' + A Lisp primitive, i.e. a Lisp-callable function implemented in C. + + Note that there is no basic "function" type, as in more powerful +versions of Lisp (where it's called a "closure"). XEmacs Lisp does not +provide the closure semantics implemented by Common Lisp and Scheme. +The guts of a function in XEmacs Lisp are represented in one of four +ways: a symbol specifying another function (when one function is an +alias for another), a list (whose first element must be the symbol +`lambda') containing the function's source code, a compiled-function +object, or a subr object. (In other words, given a symbol specifying +the name of a function, calling `symbol-function' to retrieve the +contents of the symbol's function cell will return one of these types +of objects.) + + XEmacs Lisp also contains numerous specialized objects used to +implement the editor: + +`buffer' + Stores text like a string, but is optimized for insertion and + deletion and has certain other properties that can be set. + +`frame' + An object with various properties whose displayable representation + is a "window" in window-system parlance. + +`window' + A section of a frame that displays the contents of a buffer; often + called a "pane" in window-system parlance. + +`window-configuration' + An object that represents a saved configuration of windows in a + frame. + +`device' + An object representing a screen on which frames can be displayed; + equivalent to a "display" in the X Window System and a "TTY" in + character mode. + +`face' + An object specifying the appearance of text or graphics; it has + properties such as font, foreground color, and background color. + +`marker' + An object that refers to a particular position in a buffer and + moves around as text is inserted and deleted to stay in the same + relative position to the text around it. + +`extent' + Similar to a marker but covers a range of text in a buffer; can + also specify properties of the text, such as a face in which the + text is to be displayed, whether the text is invisible or + unmodifiable, etc. + +`event' + Generated by calling `next-event' and contains information + describing a particular event happening in the system, such as the + user pressing a key or a process terminating. + +`keymap' + An object that maps from events (described using lists, vectors, + and symbols rather than with an event object because the mapping + is for classes of events, rather than individual events) to + functions to execute or other events to recursively look up; the + functions are described by name, using a symbol, or using lists to + specify the function's code. + +`glyph' + An object that describes the appearance of an image (e.g. pixmap) + on the screen; glyphs can be attached to the beginning or end of + extents and in some future version of XEmacs will be able to be + inserted directly into a buffer. + +`process' + An object that describes a connection to an externally-running + process. + + There are some other, less-commonly-encountered general objects: + +`hash-table' + An object that maps from an arbitrary Lisp object to another + arbitrary Lisp object, using hashing for fast lookup. + +`obarray' + A limited form of hash-table that maps from strings to symbols; + obarrays are used to look up a symbol given its name and are not + actually their own object type but are kludgily represented using + vectors with hidden fields (this representation derives from GNU + Emacs). + +`specifier' + A complex object used to specify the value of a display property; a + default value is given and different values can be specified for + particular frames, buffers, windows, devices, or classes of device. + +`char-table' + An object that maps from chars or classes of chars to arbitrary + Lisp objects; internally char tables use a complex nested-vector + representation that is optimized to the way characters are + represented as integers. + +`range-table' + An object that maps from ranges of integers to arbitrary Lisp + objects. + + And some strange special-purpose objects: + +`charset' +`coding-system' + Objects used when MULE, or multi-lingual/Asian-language, support is + enabled. + +`color-instance' +`font-instance' +`image-instance' + An object that encapsulates a window-system resource; instances are + mostly used internally but are exposed on the Lisp level for + cleanness of the specifier model and because it's occasionally + useful for Lisp program to create or query the properties of + instances. + +`subwindow' + An object that encapsulate a "subwindow" resource, i.e. a + window-system child window that is drawn into by an external + process; this object should be integrated into the glyph system + but isn't yet, and may change form when this is done. + +`tooltalk-message' +`tooltalk-pattern' + Objects that represent resources used in the ToolTalk interprocess + communication protocol. + +`toolbar-button' + An object used in conjunction with the toolbar. + + And objects that are only used internally: + +`opaque' + A generic object for encapsulating arbitrary memory; this allows + you the generality of `malloc()' and the convenience of the Lisp + object system. + +`lstream' + A buffering I/O stream, used to provide a unified interface to + anything that can accept output or provide input, such as a file + descriptor, a stdio stream, a chunk of memory, a Lisp buffer, a + Lisp string, etc.; it's a Lisp object to make its memory + management more convenient. + +`char-table-entry' + Subsidiary objects in the internal char-table representation. + +`extent-auxiliary' +`menubar-data' +`toolbar-data' + Various special-purpose objects that are basically just used to + encapsulate memory for particular subsystems, similar to the more + general "opaque" object. + +`symbol-value-forward' +`symbol-value-buffer-local' +`symbol-value-varalias' +`symbol-value-lisp-magic' + Special internal-only objects that are placed in the value cell of + a symbol to indicate that there is something special with this + variable - e.g. it has no value, it mirrors another variable, or + it mirrors some C variable; there is really only one kind of + object, called a "symbol-value-magic", but it is sort-of halfway + kludged into semi-different object types. + + Some types of objects are "permanent", meaning that once created, +they do not disappear until explicitly destroyed, using a function such +as `delete-buffer', `delete-window', `delete-frame', etc. Others will +disappear once they are not longer used, through the garbage collection +mechanism. Buffers, frames, windows, devices, and processes are among +the objects that are permanent. Note that some objects can go both +ways: Faces can be created either way; extents are normally permanent, +but detached extents (extents not referring to any text, as happens to +some extents when the text they are referring to is deleted) are +temporary. Note that some permanent objects, such as faces and coding +systems, cannot be deleted. Note also that windows are unique in that +they can be _undeleted_ after having previously been deleted. (This +happens as a result of restoring a window configuration.) + + Note that many types of objects have a "read syntax", i.e. a way of +specifying an object of that type in Lisp code. When you load a Lisp +file, or type in code to be evaluated, what really happens is that the +function `read' is called, which reads some text and creates an object +based on the syntax of that text; then `eval' is called, which possibly +does something special; then this loop repeats until there's no more +text to read. (`eval' only actually does something special with +symbols, which causes the symbol's value to be returned, similar to +referencing a variable; and with conses [i.e. lists], which cause a +function invocation. All other values are returned unchanged.) + + The read syntax + + 17297 + + converts to an integer whose value is 17297. + + 1.983e-4 + + converts to a float whose value is 1.983e-4, or .0001983. + + ?b + + converts to a char that represents the lowercase letter b. + + ?^[$(B#&^[(B + + (where `^[' actually is an `ESC' character) converts to a particular +Kanji character when using an ISO2022-based coding system for input. +(To decode this goo: `ESC' begins an escape sequence; `ESC $ (' is a +class of escape sequences meaning "switch to a 94x94 character set"; +`ESC $ ( B' means "switch to Japanese Kanji"; `#' and `&' collectively +index into a 94-by-94 array of characters [subtract 33 from the ASCII +value of each character to get the corresponding index]; `ESC (' is a +class of escape sequences meaning "switch to a 94 character set"; `ESC +(B' means "switch to US ASCII". It is a coincidence that the letter +`B' is used to denote both Japanese Kanji and US ASCII. If the first +`B' were replaced with an `A', you'd be requesting a Chinese Hanzi +character from the GB2312 character set.) + + "foobar" + + converts to a string. + + foobar + + converts to a symbol whose name is `"foobar"'. This is done by +looking up the string equivalent in the global variable `obarray', +whose contents should be an obarray. If no symbol is found, a new +symbol with the name `"foobar"' is automatically created and added to +`obarray'; this process is called "interning" the symbol. + + (foo . bar) + + converts to a cons cell containing the symbols `foo' and `bar'. + + (1 a 2.5) + + converts to a three-element list containing the specified objects +(note that a list is actually a set of nested conses; see the XEmacs +Lisp Reference). + + [1 a 2.5] + + converts to a three-element vector containing the specified objects. + + #[... ... ... ...] + + converts to a compiled-function object (the actual contents are not +shown since they are not relevant here; look at a file that ends with +`.elc' for examples). + + #*01110110 + + converts to a bit-vector. + + #s(hash-table ... ...) + + converts to a hash table (the actual contents are not shown). + + #s(range-table ... ...) + + converts to a range table (the actual contents are not shown). + + #s(char-table ... ...) + + converts to a char table (the actual contents are not shown). + + Note that the `#s()' syntax is the general syntax for structures, +which are not really implemented in XEmacs Lisp but should be. + + When an object is printed out (using `print' or a related function), +the read syntax is used, so that the same object can be read in again. + + The other objects do not have read syntaxes, usually because it does +not really make sense to create them in this fashion (i.e. processes, +where it doesn't make sense to have a subprocess created as a side +effect of reading some Lisp code), or because they can't be created at +all (e.g. subrs). Permanent objects, as a rule, do not have a read +syntax; nor do most complex objects, which contain too much state to be +easily initialized through a read syntax. + + +File: internals.info, Node: How Lisp Objects Are Represented in C, Next: Rules When Writing New C Code, Prev: The XEmacs Object System (Abstractly Speaking), Up: Top + +7 How Lisp Objects Are Represented in C +*************************************** + +Lisp objects are represented in C using a 32-bit or 64-bit machine word +(depending on the processor; i.e. DEC Alphas use 64-bit Lisp objects and +most other processors use 32-bit Lisp objects). The representation +stuffs a pointer together with a tag, as follows: + + [ 3 3 2 2 2 2 2 2 2 2 2 2 1 1 1 1 1 1 1 1 1 1 0 0 0 0 0 0 0 0 0 0 ] + [ 1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0 ] + + <---------------------------------------------------------> <-> + a pointer to a structure, or an integer tag + + A tag of 00 is used for all pointer object types, a tag of 10 is used +for characters, and the other two tags 01 and 11 are joined together to +form the integer object type. This representation gives us 31 bit +integers and 30 bit characters, while pointers are represented directly +without any bit masking or shifting. This representation, though, +assumes that pointers to structs are always aligned to multiples of 4, +so the lower 2 bits are always zero. + + Lisp objects use the typedef `Lisp_Object', but the actual C type +used for the Lisp object can vary. It can be either a simple type +(`long' on the DEC Alpha, `int' on other machines) or a structure whose +fields are bit fields that line up properly (actually, a union of +structures is used). The choice of which type to use is determined by +the preprocessor constant `USE_UNION_TYPE' which is defined via the +`--use-union-type' option to `configure'. + + Generally the simple integral type is preferable because it ensures +that the compiler will actually use a machine word to represent the +object (some compilers will use more general and less efficient code +for unions and structs even if they can fit in a machine word). The +union type, however, has the advantage of stricter _static_ type +checking. Places where a `Lisp_Object' is mistakenly passed to a +routine expecting an `int' (or vice-versa), or a check is written `if +(foo)' (instead of `if (!NILP (foo))', will be flagged as errors. None +of these lead to the expected results! `Qnil' is not represented as 0 +(so `if (foo)' will *ALWAYS* be true for a `Lisp_Object'), and the +representation of an integer as a `Lisp_Object' is not just the +integer's numeric value, but usually 2x the integer +/- 1.) + + There used to be a claim that the union type simplified debugging. +There may have been a grain of truth to this pre-19.8, when there was no +`lrecord' type and all objects had a separate type appearing in the +tag. Nowadays, however, there is no debugging gain, and in fact +frequent debugging *_loss_*, since many debuggers don't handle unions +very well, and usually there is no way to directly specify a union from +a debugging prompt. + + Furthermore, release builds should *_not_* be done with union type +because (a) you may get less efficiency, with compilers that can't +figure out how to optimize the union into a machine word; (b) even +worse, the union type often triggers miscompilation, especially when +combined with Mule and error-checking. This has been the case at +various times when using GCC and MS VC, at least with `--pdump'. +Therefore, be warned! + + As of 2002 4Q, miscompilation is known to happen with current +versions of *Microsoft VC++* and *GCC in combination with Mule, pdump, +and KKCC* (no error checking). + + Various macros are used to convert between Lisp_Objects and the +corresponding C type. Macros of the form `XINT()', `XCHAR()', +`XSTRING()', `XSYMBOL()', do any required bit shifting and/or masking +and cast it to the appropriate type. `XINT()' needs to be a bit tricky +so that negative numbers are properly sign-extended. Since integers +are stored left-shifted, if the right-shift operator does an arithmetic +shift (i.e. it leaves the most-significant bit as-is rather than +shifting in a zero, so that it mimics a divide-by-two even for negative +numbers) the shift to remove the tag bit is enough. This is the case +on all the systems we support. + + Note that when `ERROR_CHECK_TYPECHECK' is defined, the converter +macros become more complicated--they check the tag bits and/or the type +field in the first four bytes of a record type to ensure that the +object is really of the correct type. This is great for catching places +where an incorrect type is being dereferenced--this typically results +in a pointer being dereferenced as the wrong type of structure, with +unpredictable (and sometimes not easily traceable) results. + + There are similar `XSETTYPE()' macros that construct a Lisp object. +These macros are of the form `XSETTYPE (LVALUE, RESULT)', i.e. they +have to be a statement rather than just used in an expression. The +reason for this is that standard C doesn't let you "construct" a +structure (but GCC does). Granted, this sometimes isn't too +convenient; for the case of integers, at least, you can use the +function `make_int()', which constructs and _returns_ an integer Lisp +object. Note that the `XSETTYPE()' macros are also affected by +`ERROR_CHECK_TYPECHECK' and make sure that the structure is of the +right type in the case of record types, where the type is contained in +the structure. + + The C programmer is responsible for *guaranteeing* that a +Lisp_Object is the correct type before using the `XTYPE' macros. This +is especially important in the case of lists. Use `XCAR' and `XCDR' if +a Lisp_Object is certainly a cons cell, else use `Fcar()' and `Fcdr()'. +Trust other C code, but not Lisp code. On the other hand, if XEmacs +has an internal logic error, it's better to crash immediately, so +sprinkle `assert()'s and "unreachable" `abort()'s liberally about the +source code. Where performance is an issue, use `type_checking_assert', +`bufpos_checking_assert', and `gc_checking_assert', which do nothing +unless the corresponding configure error checking flag was specified. + + +File: internals.info, Node: Rules When Writing New C Code, Next: Regression Testing XEmacs, Prev: How Lisp Objects Are Represented in C, Up: Top + +8 Rules When Writing New C Code +******************************* + +The XEmacs C Code is extremely complex and intricate, and there are many +rules that are more or less consistently followed throughout the code. +Many of these rules are not obvious, so they are explained here. It is +of the utmost importance that you follow them. If you don't, you may +get something that appears to work, but which will crash in odd +situations, often in code far away from where the actual breakage is. + +* Menu: + +* A Reader's Guide to XEmacs Coding Conventions:: +* General Coding Rules:: +* Writing Lisp Primitives:: +* Writing Good Comments:: +* Adding Global Lisp Variables:: +* Proper Use of Unsigned Types:: +* Coding for Mule:: +* Techniques for XEmacs Developers:: + + +File: internals.info, Node: A Reader's Guide to XEmacs Coding Conventions, Next: General Coding Rules, Up: Rules When Writing New C Code + +8.1 A Reader's Guide to XEmacs Coding Conventions +================================================= + +Of course the low-level implementation language of XEmacs is C, but much +of that uses the Lisp engine to do its work. However, because the code +is "inside" of the protective containment shell around the "reactor +core," you'll see lots of complex "plumbing" needed to do the work and +"safety mechanisms," whose failure results in a meltdown. This section +provides a quick overview (or review) of the various components of the +implementation of Lisp objects. + + Two typographic conventions help to identify C objects that implement +Lisp objects. The first is that capitalized identifiers, especially +beginning with the letters `Q', `V', `F', and `S', for C variables and +functions, and C macros with beginning with the letter `X', are used to +implement Lisp. The second is that where Lisp uses the hyphen `-' in +symbol names, the corresponding C identifiers use the underscore `_'. +Of course, since XEmacs Lisp contains interfaces to many external +libraries, those external names will follow the coding conventions +their authors chose, and may overlap the "XEmacs name space." However +these cases are usually pretty obvious. + + All Lisp objects are handled indirectly. The `Lisp_Object' type is +usually a pointer to a structure, except for a very small number of +types with immediate representations (currently characters and +integers). However, these types cannot be directly operated on in C +code, either, so they can also be considered indirect. Types that do +not have an immediate representation always have a C typedef +`Lisp_TYPE' for a corresponding structure. + + In older code, it was common practice to pass around pointers to +`Lisp_TYPE', but this is now deprecated in favor of using `Lisp_Object' +for all function arguments and return values that are Lisp objects. +The `XTYPE' macro is used to extract the pointer and cast it to +`(Lisp_TYPE *)' for the desired type. + + *Convention*: macros whose names begin with `X' operate on +`Lisp_Object's and do no type-checking. Many such macros are type +extractors, but others implement Lisp operations in C (_e.g._, `XCAR' +implements the Lisp `car' function). These are unsafe, and must only +be used where types of all data have already been checked. Such macros +are only applied to `Lisp_Object's. In internal implementations where +the pointer has already been converted, the structure is operated on +directly using the C `->' member access operator. + + The `TYPEP', `CHECK_TYPE', and `CONCHECK_TYPE' macros are used to +test types. The first returns a Boolean value, and the latter signal +errors. (The `CONCHECK' variety allows execution to be CONtinued under +some circumstances, thus the name.) Functions which expect to be +passed user data invariably call `CHECK' macros on arguments. + + There are many types of specialized Lisp objects implemented in C, +but the most pervasive type is the "symbol". Symbols are used as +identifiers, variables, and functions. + + *Convention*: Global variables whose names begin with `Q' are +constants whose value is a symbol. The name of the variable should be +derived from the name of the symbol using the same rules as for Lisp +primitives. Such variables allow the C code to check whether a +particular `Lisp_Object' is equal to a given symbol. Symbols are Lisp +objects, so these variables may be passed to Lisp primitives. (An +alternative to the use of `Q...' variables is to call the `intern' +function at initialization in the `vars_of_MODULE' function, which is +hardly less efficient.) + + *Convention*: Global variables whose names begin with `V' are +variables that contain Lisp objects. The convention here is that all +global variables of type `Lisp_Object' begin with `V', and no others do +(not even integer and boolean variables that have Lisp equivalents). +Most of the time, these variables have equivalents in Lisp, which are +defined via the `DEFVAR' family of macros, but some don't. Since the +variable's value is a `Lisp_Object', it can be passed to Lisp +primitives. + + The implementation of Lisp primitives is more complex. +*Convention*: Global variables with names beginning with `S' contain a +structure that allows the Lisp engine to identify and call a C +function. In modern versions of XEmacs, these identifiers are almost +always completely hidden in the `DEFUN' and `SUBR' macros, but you will +encounter them if you look at very old versions of XEmacs or at GNU +Emacs. *Convention*: Functions with names beginning with `F' implement +Lisp primitives. Of course all their arguments and their return values +must be Lisp_Objects. (This is hidden in the `DEFUN' macro.) + + +File: internals.info, Node: General Coding Rules, Next: Writing Lisp Primitives, Prev: A Reader's Guide to XEmacs Coding Conventions, Up: Rules When Writing New C Code + +8.2 General Coding Rules +======================== + +The C code is actually written in a dialect of C called "Clean C", +meaning that it can be compiled, mostly warning-free, with either a C or +C++ compiler. Coding in Clean C has several advantages over plain C. +C++ compilers are more nit-picking, and a number of coding errors have +been found by compiling with C++. The ability to use both C and C++ +tools means that a greater variety of development tools are available to +the developer. + + Every module includes `' (angle brackets so that +`--srcdir' works correctly; `config.h' may or may not be in the same +directory as the C sources) and `lisp.h'. `config.h' must always be +included before any other header files (including system header files) +to ensure that certain tricks played by various `s/' and `m/' files +work out correctly. + + When including header files, always use angle brackets, not double +quotes, except when the file to be included is always in the same +directory as the including file. If either file is a generated file, +then that is not likely to be the case. In order to understand why we +have this rule, imagine what happens when you do a build in the source +directory using `./configure' and another build in another directory +using `../work/configure'. There will be two different `config.h' +files. Which one will be used if you `#include "config.h"'? + + Almost every module contains a `syms_of_*()' function and a +`vars_of_*()' function. The former declares any Lisp primitives you +have defined and defines any symbols you will be using. The latter +declares any global Lisp variables you have added and initializes global +C variables in the module. *Important*: There are stringent +requirements on exactly what can go into these functions. See the +comment in `emacs.c'. The reason for this is to avoid obscure unwanted +interactions during initialization. If you don't follow these rules, +you'll be sorry! If you want to do anything that isn't allowed, create +a `complex_vars_of_*()' function for it. Doing this is tricky, though: +you have to make sure your function is called at the right time so that +all the initialization dependencies work out. + + Declare each function of these kinds in `symsinit.h'. Make sure +it's called in the appropriate place in `emacs.c'. You never need to +include `symsinit.h' directly, because it is included by `lisp.h'. + + *All global and static variables that are to be modifiable must be +declared uninitialized.* This means that you may not use the "declare +with initializer" form for these variables, such as `int some_variable += 0;'. The reason for this has to do with some kludges done during the +dumping process: If possible, the initialized data segment is re-mapped +so that it becomes part of the (unmodifiable) code segment in the +dumped executable. This allows this memory to be shared among multiple +running XEmacs processes. XEmacs is careful to place as much constant +data as possible into initialized variables during the `temacs' phase. + + *Please note:* This kludge only works on a few systems nowadays, and +is rapidly becoming irrelevant because most modern operating systems +provide "copy-on-write" semantics. All data is initially shared +between processes, and a private copy is automatically made (on a +page-by-page basis) when a process first attempts to write to a page of +memory. + + Formerly, there was a requirement that static variables not be +declared inside of functions. This had to do with another hack along +the same vein as what was just described: old USG systems put +statically-declared variables in the initialized data space, so those +header files had a `#define static' declaration. (That way, the +data-segment remapping described above could still work.) This fails +badly on static variables inside of functions, which suddenly become +automatic variables; therefore, you weren't supposed to have any of +them. This awful kludge has been removed in XEmacs because + + 1. almost all of the systems that used this kludge ended up having to + disable the data-segment remapping anyway; + + 2. the only systems that didn't were extremely outdated ones; + + 3. this hack completely messed up inline functions. + + The C source code makes heavy use of C preprocessor macros. One +popular macro style is: + + #define FOO(var, value) do { \ + Lisp_Object FOO_value = (value); \ + ... /* compute using FOO_value */ \ + (var) = bar; \ + } while (0) + + The `do {...} while (0)' is a standard trick to allow FOO to have +statement semantics, so that it can safely be used within an `if' +statement in C, for example. Multiple evaluation is prevented by +copying a supplied argument into a local variable, so that +`FOO(var,fun(1))' only calls `fun' once. + + Lisp lists are popular data structures in the C code as well as in +Elisp. There are two sets of macros that iterate over lists. +`EXTERNAL_LIST_LOOP_N' should be used when the list has been supplied +by the user, and cannot be trusted to be acyclic and `nil'-terminated. +A `malformed-list' or `circular-list' error will be generated if the +list being iterated over is not entirely kosher. `LIST_LOOP_N', on the +other hand, is faster and less safe, and can be used only on trusted +lists. + + Related macros are `GET_EXTERNAL_LIST_LENGTH' and `GET_LIST_LENGTH', +which calculate the length of a list, and in the case of +`GET_EXTERNAL_LIST_LENGTH', validating the properness of the list. The +macros `EXTERNAL_LIST_LOOP_DELETE_IF' and `LIST_LOOP_DELETE_IF' delete +elements from a lisp list satisfying some predicate. + + +File: internals.info, Node: Writing Lisp Primitives, Next: Writing Good Comments, Prev: General Coding Rules, Up: Rules When Writing New C Code + +8.3 Writing Lisp Primitives +=========================== + +Lisp primitives are Lisp functions implemented in C. The details of +interfacing the C function so that Lisp can call it are handled by a few +C macros. The only way to really understand how to write new C code is +to read the source, but we can explain some things here. + + An example of a special form is the definition of `prog1', from +`eval.c'. (An ordinary function would have the same general +appearance.) + + DEFUN ("prog1", Fprog1, 1, UNEVALLED, 0, /* + Similar to `progn', but the value of the first form is returned. + \(prog1 FIRST BODY...): All the arguments are evaluated sequentially. + The value of FIRST is saved during evaluation of the remaining args, + whose values are discarded. + */ + (args)) + { + /* This function can GC */ + REGISTER Lisp_Object val, form, tail; + struct gcpro gcpro1; + + val = Feval (XCAR (args)); + + GCPRO1 (val); + + LIST_LOOP_3 (form, XCDR (args), tail) + Feval (form); + + UNGCPRO; + return val; + } + + Let's start with a precise explanation of the arguments to the +`DEFUN' macro. Here is a template for them: + + DEFUN (LNAME, FNAME, MIN_ARGS, MAX_ARGS, INTERACTIVE, /* + DOCSTRING + */ + (ARGLIST)) + +LNAME + This string is the name of the Lisp symbol to define as the + function name; in the example above, it is `"prog1"'. + +FNAME + This is the C function name for this function. This is the name + that is used in C code for calling the function. The name is, by + convention, `F' prepended to the Lisp name, with all dashes (`-') + in the Lisp name changed to underscores. Thus, to call this + function from C code, call `Fprog1'. Remember that the arguments + are of type `Lisp_Object'; various macros and functions for + creating values of type `Lisp_Object' are declared in the file + `lisp.h'. + + Primitives whose names are special characters (e.g. `+' or `<') + are named by spelling out, in some fashion, the special character: + e.g. `Fplus()' or `Flss()'. Primitives whose names begin with + normal alphanumeric characters but also contain special characters + are spelled out in some creative way, e.g. `let*' becomes + `FletX()'. + + Each function also has an associated structure that holds the data + for the subr object that represents the function in Lisp. This + structure conveys the Lisp symbol name to the initialization + routine that will create the symbol and store the subr object as + its definition. The C variable name of this structure is always + `S' prepended to the FNAME. You hardly ever need to be aware of + the existence of this structure, since `DEFUN' plus `DEFSUBR' + takes care of all the details. + +MIN_ARGS + This is the minimum number of arguments that the function + requires. The function `prog1' allows a minimum of one argument. + +MAX_ARGS + This is the maximum number of arguments that the function accepts, + if there is a fixed maximum. Alternatively, it can be `UNEVALLED', + indicating a special form that receives unevaluated arguments, or + `MANY', indicating an unlimited number of evaluated arguments (the + C equivalent of `&rest'). Both `UNEVALLED' and `MANY' are macros. + If MAX_ARGS is a number, it may not be less than MIN_ARGS and it + may not be greater than 8. (If you need to add a function with + more than 8 arguments, use the `MANY' form. Resist the urge to + edit the definition of `DEFUN' in `lisp.h'. If you do it anyways, + make sure to also add another clause to the switch statement in + `primitive_funcall().') + +INTERACTIVE + This is an interactive specification, a string such as might be + used as the argument of `interactive' in a Lisp function. In the + case of `prog1', it is 0 (a null pointer), indicating that `prog1' + cannot be called interactively. A value of `""' indicates a + function that should receive no arguments when called + interactively. + +DOCSTRING + This is the documentation string. It is written just like a + documentation string for a function defined in Lisp; in + particular, the first line should be a single sentence. Note how + the documentation string is enclosed in a comment, none of the + documentation is placed on the same lines as the comment-start and + comment-end characters, and the comment-start characters are on + the same line as the interactive specification. `make-docfile', + which scans the C files for documentation strings, is very + particular about what it looks for, and will not properly extract + the doc string if it's not in this exact format. + + In order to make both `etags' and `make-docfile' happy, make sure + that the `DEFUN' line contains the LNAME and FNAME, and that the + comment-start characters for the doc string are on the same line + as the interactive specification, and put a newline directly after + them (and before the comment-end characters). + +ARGLIST + This is the comma-separated list of arguments to the C function. + For a function with a fixed maximum number of arguments, provide a + C argument for each Lisp argument. In this case, unlike regular C + functions, the types of the arguments are not declared; they are + simply always of type `Lisp_Object'. + + The names of the C arguments will be used as the names of the + arguments to the Lisp primitive as displayed in its documentation, + modulo the same concerns described above for `F...' names (in + particular, underscores in the C arguments become dashes in the + Lisp arguments). + + There is one additional kludge: A trailing `_' on the C argument is + discarded when forming the Lisp argument. This allows C language + reserved words (like `default') or global symbols (like `dirname') + to be used as argument names without compiler warnings or errors. + + A Lisp function with MAX_ARGS = `UNEVALLED' is a "special form"; + its arguments are not evaluated. Instead it receives one argument + of type `Lisp_Object', a (Lisp) list of the unevaluated arguments, + conventionally named `(args)'. + + When a Lisp function has no upper limit on the number of arguments, + specify MAX_ARGS = `MANY'. In this case its implementation in C + actually receives exactly two arguments: the number of Lisp + arguments (an `int') and the address of a block containing their + values (a `Lisp_Object *'). In this case only are the C types + specified in the ARGLIST: `(int nargs, Lisp_Object *args)'. + + + Within the function `Fprog1' itself, note the use of the macros +`GCPRO1' and `UNGCPRO'. `GCPRO1' is used to "protect" a variable from +garbage collection--to inform the garbage collector that it must look +in that variable and regard the object pointed at by its contents as an +accessible object. This is necessary whenever you call `Feval' or +anything that can directly or indirectly call `Feval' (this includes +the `QUIT' macro!). At such a time, any Lisp object that you intend to +refer to again must be protected somehow. `UNGCPRO' cancels the +protection of the variables that are protected in the current function. +It is necessary to do this explicitly. + + The macro `GCPRO1' protects just one local variable. If you want to +protect two, use `GCPRO2' instead; repeating `GCPRO1' will not work. +Macros `GCPRO3' and `GCPRO4' also exist. + + These macros implicitly use local variables such as `gcpro1'; you +must declare these explicitly, with type `struct gcpro'. Thus, if you +use `GCPRO2', you must declare `gcpro1' and `gcpro2'. + + Note also that the general rule is "caller-protects"; i.e. you are +only responsible for protecting those Lisp objects that you create. Any +objects passed to you as arguments should have been protected by whoever +created them, so you don't in general have to protect them. + + In particular, the arguments to any Lisp primitive are always +automatically `GCPRO'ed, when called "normally" from Lisp code or +bytecode. So only a few Lisp primitives that are called frequently from +C code, such as `Fprogn' protect their arguments as a service to their +caller. You don't need to protect your arguments when writing a new +`DEFUN'. + + `GCPRO'ing is perhaps the trickiest and most error-prone part of +XEmacs coding. It is *extremely* important that you get this right and +use a great deal of discipline when writing this code. *Note +`GCPRO'ing: GCPROing, for full details on how to do this. + + What `DEFUN' actually does is declare a global structure of type +`Lisp_Subr' whose name begins with capital `SF' and which contains +information about the primitive (e.g. a pointer to the function, its +minimum and maximum allowed arguments, a string describing its Lisp +name); `DEFUN' then begins a normal C function declaration using the +`F...' name. The Lisp subr object that is the function definition of a +primitive (i.e. the object in the function slot of the symbol that +names the primitive) actually points to this `SF' structure; when +`Feval' encounters a subr, it looks in the structure to find out how to +call the C function. + + Defining the C function is not enough to make a Lisp primitive +available; you must also create the Lisp symbol for the primitive (the +symbol is "interned"; *note Obarrays::) and store a suitable subr +object in its function cell. (If you don't do this, the primitive won't +be seen by Lisp code.) The code looks like this: + + DEFSUBR (FNAME); + +Here FNAME is the same name you used as the second argument to `DEFUN'. + + This call to `DEFSUBR' should go in the `syms_of_*()' function at +the end of the module. If no such function exists, create it and make +sure to also declare it in `symsinit.h' and call it from the +appropriate spot in `main()'. *Note General Coding Rules::. + + Note that C code cannot call functions by name unless they are +defined in C. The way to call a function written in Lisp from C is to +use `Ffuncall', which embodies the Lisp function `funcall'. Since the +Lisp function `funcall' accepts an unlimited number of arguments, in C +it takes two: the number of Lisp-level arguments, and a one-dimensional +array containing their values. The first Lisp-level argument is the +Lisp function to call, and the rest are the arguments to pass to it. +Since `Ffuncall' can call the evaluator, you must protect pointers from +garbage collection around the call to `Ffuncall'. (However, `Ffuncall' +explicitly protects all of its parameters, so you don't have to protect +any pointers passed as parameters to it.) + + The C functions `call0', `call1', `call2', and so on, provide handy +ways to call a Lisp function conveniently with a fixed number of +arguments. They work by calling `Ffuncall'. + + `eval.c' is a very good file to look through for examples; `lisp.h' +contains the definitions for important macros and functions. + + +File: internals.info, Node: Writing Good Comments, Next: Adding Global Lisp Variables, Prev: Writing Lisp Primitives, Up: Rules When Writing New C Code + +8.4 Writing Good Comments +========================= + +Comments are a lifeline for programmers trying to understand tricky +code. In general, the less obvious it is what you are doing, the more +you need a comment, and the more detailed it needs to be. You should +always be on guard when you're writing code for stuff that's tricky, and +should constantly be putting yourself in someone else's shoes and asking +if that person could figure out without much difficulty what's going +on. (Assume they are a competent programmer who understands the +essentials of how the XEmacs code is structured but doesn't know much +about the module you're working on or any algorithms you're using.) If +you're not sure whether they would be able to, add a comment. Always +err on the side of more comments, rather than less. + + Generally, when making comments, there is no need to attribute them +with your name or initials. This especially goes for small, +easy-to-understand, non-opinionated ones. Also, comments indicating +where, when, and by whom a file was changed are _strongly_ discouraged, +and in general will be removed as they are discovered. This is exactly +what `ChangeLogs' are there for. However, it can occasionally be +useful to mark exactly where (but not when or by whom) changes are +made, particularly when making small changes to a file imported from +elsewhere. These marks help when later on a newer version of the file +is imported and the changes need to be merged. (If everything were +always kept in CVS, there would be no need for this. But in practice, +this often doesn't happen, or the CVS repository is later on lost or +unavailable to the person doing the update.) + + When putting in an explicit opinion in a comment, you should +_always_ attribute it with your name, and optionally the date. This +also goes for long, complex comments explaining in detail the workings +of something - by putting your name there, you make it possible for +someone who has questions about how that thing works to determine who +wrote the comment so they can write to them. Preferably, use your +actual name and not your initials, unless your initials are generally +recognized (e.g. `jwz'). You can use only your first name if it's +obvious who you are; otherwise, give first and last name. If you're +not a regular contributor, you might consider putting your email +address in - it may be in the ChangeLog, but after awhile ChangeLogs +have a tendency of disappearing or getting muddled. (E.g. your comment +may get copied somewhere else or even into another program, and +tracking down the proper ChangeLog may be very difficult.) + + If you come across an opinion that is not or no longer valid, or you +come across any comment that no longer applies but you want to keep it +around, enclose it in `[[ ' and ` ]]' marks and add a comment +afterwards explaining why the preceding comment is no longer valid. Put +your name on this comment, as explained above. + + Just as comments are a lifeline to programmers, incorrect comments +are death. If you come across an incorrect comment, *immediately* +correct it or flag it as incorrect, as described in the previous +paragraph. Whenever you work on a section of code, _always_ make sure +to update any comments to be correct - or, at the very least, flag them +as incorrect. + + To indicate a "todo" or other problem, use four pound signs - i.e. +`####'. + + +File: internals.info, Node: Adding Global Lisp Variables, Next: Proper Use of Unsigned Types, Prev: Writing Good Comments, Up: Rules When Writing New C Code + +8.5 Adding Global Lisp Variables +================================ + +Global variables whose names begin with `Q' are constants whose value +is a symbol of a particular name. The name of the variable should be +derived from the name of the symbol using the same rules as for Lisp +primitives. These variables are initialized using a call to +`defsymbol()' in the `syms_of_*()' function. (This call interns a +symbol, sets the C variable to the resulting Lisp object, and calls +`staticpro()' on the C variable to tell the garbage-collection +mechanism about this variable. What `staticpro()' does is add a +pointer to the variable to a large global array; when +garbage-collection happens, all pointers listed in the array are used +as starting points for marking Lisp objects. This is important because +it's quite possible that the only current reference to the object is +the C variable. In the case of symbols, the `staticpro()' doesn't +matter all that much because the symbol is contained in `obarray', +which is itself `staticpro()'ed. However, it's possible that a naughty +user could do something like uninterning the symbol out of `obarray' or +even setting `obarray' to a different value [although this is likely to +make XEmacs crash!].) + + *Please note:* It is potentially deadly if you declare a `Q...' +variable in two different modules. The two calls to `defsymbol()' are +no problem, but some linkers will complain about multiply-defined +symbols. The most insidious aspect of this is that often the link will +succeed anyway, but then the resulting executable will sometimes crash +in obscure ways during certain operations! + + To avoid this problem, declare any symbols with common names (such as +`text') that are not obviously associated with this particular module +in the file `general-slots.h'. The "-slots" suffix indicates that this +is a file that is included multiple times in `general.c'. Redefinition +of preprocessor macros allows the effects to be different in each +context, so this is actually more convenient and less error-prone than +doing it in your module. + + Global variables whose names begin with `V' are variables that +contain Lisp objects. The convention here is that all global variables +of type `Lisp_Object' begin with `V', and all others don't (including +integer and boolean variables that have Lisp equivalents). Most of the +time, these variables have equivalents in Lisp, but some don't. Those +that do are declared this way by a call to `DEFVAR_LISP()' in the +`vars_of_*()' initializer for the module. What this does is create a +special "symbol-value-forward" Lisp object that contains a pointer to +the C variable, intern a symbol whose name is as specified in the call +to `DEFVAR_LISP()', and set its value to the symbol-value-forward Lisp +object; it also calls `staticpro()' on the C variable to tell the +garbage-collection mechanism about the variable. When `eval' (or +actually `symbol-value') encounters this special object in the process +of retrieving a variable's value, it follows the indirection to the C +variable and gets its value. `setq' does similar things so that the C +variable gets changed. + + Whether or not you `DEFVAR_LISP()' a variable, you need to +initialize it in the `vars_of_*()' function; otherwise it will end up +as all zeroes, which is the integer 0 (_not_ `nil'), and this is +probably not what you want. Also, if the variable is not +`DEFVAR_LISP()'ed, *you must call* `staticpro()' on the C variable in +the `vars_of_*()' function. Otherwise, the garbage-collection +mechanism won't know that the object in this variable is in use, and +will happily collect it and reuse its storage for another Lisp object, +and you will be the one who's unhappy when you can't figure out how +your variable got overwritten. + + +File: internals.info, Node: Proper Use of Unsigned Types, Next: Coding for Mule, Prev: Adding Global Lisp Variables, Up: Rules When Writing New C Code + +8.6 Proper Use of Unsigned Types +================================ + +Avoid using `unsigned int' and `unsigned long' whenever possible. +Unsigned types are viral - any arithmetic or comparisons involving +mixed signed and unsigned types are automatically converted to +unsigned, which is almost certainly not what you want. Many subtle and +hard-to-find bugs are created by careless use of unsigned types. In +general, you should almost _never_ use an unsigned type to hold a +regular quantity of any sort. The only exceptions are + + 1. When there's a reasonable possibility you will actually need all + 32 or 64 bits to store the quantity. + + 2. When calling existing API's that require unsigned types. In this + case, you should still do all manipulation using signed types, and + do the conversion at the very threshold of the API call. + + 3. In existing code that you don't want to modify because you don't + maintain it. + + 4. In bit-field structures. + + Other reasonable uses of `unsigned int' and `unsigned long' are +representing non-quantities - e.g. bit-oriented flags and such. + + +File: internals.info, Node: Coding for Mule, Next: Techniques for XEmacs Developers, Prev: Proper Use of Unsigned Types, Up: Rules When Writing New C Code + +8.7 Coding for Mule +=================== + +Although Mule support is not compiled by default in XEmacs, many people +are using it, and we consider it crucial that new code works correctly +with multibyte characters. This is not hard; it is only a matter of +following several simple user-interface guidelines. Even if you never +compile with Mule, with a little practice you will find it quite easy +to code Mule-correctly. + + Note that these guidelines are not necessarily tied to the current +Mule implementation; they are also a good idea to follow on the grounds +of code generalization for future I18N work. + +* Menu: + +* Character-Related Data Types:: +* Working With Character and Byte Positions:: +* Conversion to and from External Data:: +* General Guidelines for Writing Mule-Aware Code:: +* An Example of Mule-Aware Code:: + + +File: internals.info, Node: Character-Related Data Types, Next: Working With Character and Byte Positions, Up: Coding for Mule + +8.7.1 Character-Related Data Types +---------------------------------- + +First, let's review the basic character-related datatypes used by +XEmacs. Note that the separate `typedef's are not mandatory in the +current implementation (all of them boil down to `unsigned char' or +`int'), but they improve clarity of code a great deal, because one +glance at the declaration can tell the intended use of the variable. + +`Emchar' + An `Emchar' holds a single Emacs character. + + Obviously, the equality between characters and bytes is lost in + the Mule world. Characters can be represented by one or more + bytes in the buffer, and `Emchar' is the C type large enough to + hold any character. + + Without Mule support, an `Emchar' is equivalent to an `unsigned + char'. + +`Bufbyte' + The data representing the text in a buffer or string is logically + a set of `Bufbyte's. + + XEmacs does not work with the same character formats all the time; + when reading characters from the outside, it decodes them to an + internal format, and likewise encodes them when writing. + `Bufbyte' (in fact `unsigned char') is the basic unit of XEmacs + internal buffers and strings format. A `Bufbyte *' is the type + that points at text encoded in the variable-width internal + encoding. + + One character can correspond to one or more `Bufbyte's. In the + current Mule implementation, an ASCII character is represented by + the same `Bufbyte', and other characters are represented by a + sequence of two or more `Bufbyte's. + + Without Mule support, there are exactly 256 characters, implicitly + Latin-1, and each character is represented using one `Bufbyte', and + there is a one-to-one correspondence between `Bufbyte's and + `Emchar's. + +`Bufpos' +`Charcount' + A `Bufpos' represents a character position in a buffer or string. + A `Charcount' represents a number (count) of characters. + Logically, subtracting two `Bufpos' values yields a `Charcount' + value. Although all of these are `typedef'ed to `EMACS_INT', we + use them in preference to `EMACS_INT' to make it clear what sort + of position is being used. + + `Bufpos' and `Charcount' values are the only ones that are ever + visible to Lisp. + +`Bytind' +`Bytecount' + A `Bytind' represents a byte position in a buffer or string. A + `Bytecount' represents the distance between two positions, in + bytes. The relationship between `Bytind' and `Bytecount' is the + same as the relationship between `Bufpos' and `Charcount'. + +`Extbyte' +`Extcount' + When dealing with the outside world, XEmacs works with `Extbyte's, + which are equivalent to `unsigned char'. Obviously, an `Extcount' + is the distance between two `Extbyte's. Extbytes and Extcounts + are not all that frequent in XEmacs code. + + +File: internals.info, Node: Working With Character and Byte Positions, Next: Conversion to and from External Data, Prev: Character-Related Data Types, Up: Coding for Mule + +8.7.2 Working With Character and Byte Positions +----------------------------------------------- + +Now that we have defined the basic character-related types, we can look +at the macros and functions designed for work with them and for +conversion between them. Most of these macros are defined in +`buffer.h', and we don't discuss all of them here, but only the most +important ones. Examining the existing code is the best way to learn +about them. + +`MAX_EMCHAR_LEN' + This preprocessor constant is the maximum number of buffer bytes to + represent an Emacs character in the variable width internal + encoding. It is useful when allocating temporary strings to keep + a known number of characters. For instance: + + { + Charcount cclen; + ... + { + /* Allocate place for CCLEN characters. */ + Bufbyte *buf = (Bufbyte *)alloca (cclen * MAX_EMCHAR_LEN); + ... + + If you followed the previous section, you can guess that, + logically, multiplying a `Charcount' value with `MAX_EMCHAR_LEN' + produces a `Bytecount' value. + + In the current Mule implementation, `MAX_EMCHAR_LEN' equals 4. + Without Mule, it is 1. + +`charptr_emchar' +`set_charptr_emchar' + The `charptr_emchar' macro takes a `Bufbyte' pointer and returns + the `Emchar' stored at that position. If it were a function, its + prototype would be: + + Emchar charptr_emchar (Bufbyte *p); + + `set_charptr_emchar' stores an `Emchar' to the specified byte + position. It returns the number of bytes stored: + + Bytecount set_charptr_emchar (Bufbyte *p, Emchar c); + + It is important to note that `set_charptr_emchar' is safe only for + appending a character at the end of a buffer, not for overwriting a + character in the middle. This is because the width of characters + varies, and `set_charptr_emchar' cannot resize the string if it + writes, say, a two-byte character where a single-byte character + used to reside. + + A typical use of `set_charptr_emchar' can be demonstrated by this + example, which copies characters from buffer BUF to a temporary + string of Bufbytes. + + { + Bufpos pos; + for (pos = beg; pos < end; pos++) + { + Emchar c = BUF_FETCH_CHAR (buf, pos); + p += set_charptr_emchar (buf, c); + } + } + + Note how `set_charptr_emchar' is used to store the `Emchar' and + increment the counter, at the same time. + +`INC_CHARPTR' +`DEC_CHARPTR' + These two macros increment and decrement a `Bufbyte' pointer, + respectively. They will adjust the pointer by the appropriate + number of bytes according to the byte length of the character + stored there. Both macros assume that the memory address is + located at the beginning of a valid character. + + Without Mule support, `INC_CHARPTR (p)' and `DEC_CHARPTR (p)' + simply expand to `p++' and `p--', respectively. + +`bytecount_to_charcount' + Given a pointer to a text string and a length in bytes, return the + equivalent length in characters. + + Charcount bytecount_to_charcount (Bufbyte *p, Bytecount bc); + +`charcount_to_bytecount' + Given a pointer to a text string and a length in characters, + return the equivalent length in bytes. + + Bytecount charcount_to_bytecount (Bufbyte *p, Charcount cc); + +`charptr_n_addr' + Return a pointer to the beginning of the character offset CC (in + characters) from P. + + Bufbyte *charptr_n_addr (Bufbyte *p, Charcount cc); + + +File: internals.info, Node: Conversion to and from External Data, Next: General Guidelines for Writing Mule-Aware Code, Prev: Working With Character and Byte Positions, Up: Coding for Mule + +8.7.3 Conversion to and from External Data +------------------------------------------ + +When an external function, such as a C library function, returns a +`char' pointer, you should almost never treat it as `Bufbyte'. This is +because these returned strings may contain 8bit characters which can be +misinterpreted by XEmacs, and cause a crash. Likewise, when exporting +a piece of internal text to the outside world, you should always +convert it to an appropriate external encoding, lest the internal stuff +(such as the infamous \201 characters) leak out. + + The interface to conversion between the internal and external +representations of text are the numerous conversion macros defined in +`buffer.h'. There used to be a fixed set of external formats supported +by these macros, but now any coding system can be used with these +macros. The coding system alias mechanism is used to create the +following logical coding systems, which replace the fixed external +formats. The (dontusethis-set-symbol-value-handler) mechanism was +enhanced to make this possible (more work on that is needed - like +remove the `dontusethis-' prefix). + +`Qbinary' + This is the simplest format and is what we use in the absence of a + more appropriate format. This converts according to the `binary' + coding system: + + a. On input, bytes 0-255 are converted into (implicitly Latin-1) + characters 0-255. A non-Mule xemacs doesn't really know about + different character sets and the fonts to display them, so + the bytes can be treated as text in different 1-byte + encodings by simply setting the appropriate fonts. So in a + sense, non-Mule xemacs is a multi-lingual editor if, for + example, different fonts are used to display text in + different buffers, faces, or windows. The specifier + mechanism gives the user complete control over this kind of + behavior. + + b. On output, characters 0-255 are converted into bytes 0-255 + and other characters are converted into `~'. + +`Qfile_name' + Format used for filenames. This is user-definable via either the + `file-name-coding-system' or `pathname-coding-system' (now + obsolete) variables. + +`Qnative' + Format used for the external Unix environment--`argv[]', stuff + from `getenv()', stuff from the `/etc/passwd' file, etc. + Currently this is the same as Qfile_name. The two should be + distinguished for clarity and possible future separation. + +`Qctext' + Compound-text format. This is the standard X11 format used for + data stored in properties, selections, and the like. This is an + 8-bit no-lock-shift ISO2022 coding system. This is a real coding + system, unlike Qfile_name, which is user-definable. + + There are two fundamental macros to convert between external and +internal format. + + `TO_INTERNAL_FORMAT' converts external data to internal format, and +`TO_EXTERNAL_FORMAT' converts the other way around. The arguments each +of these receives are a source type, a source, a sink type, a sink, and +a coding system (or a symbol naming a coding system). + + A typical call looks like + TO_EXTERNAL_FORMAT (LISP_STRING, str, C_STRING_MALLOC, ptr, Qfile_name); + + which means that the contents of the lisp string `str' are written +to a malloc'ed memory area which will be pointed to by `ptr', after the +function returns. The conversion will be done using the `file-name' +coding system, which will be controlled by the user indirectly by +setting or binding the variable `file-name-coding-system'. + + Some sources and sinks require two C variables to specify. We use +some preprocessor magic to allow different source and sink types, and +even different numbers of arguments to specify different types of +sources and sinks. + + So we can have a call that looks like + TO_INTERNAL_FORMAT (DATA, (ptr, len), + MALLOC, (ptr, len), + coding_system); + + The parenthesized argument pairs are required to make the +preprocessor magic work. + + Here are the different source and sink types: + +``DATA, (ptr, len),'' + input data is a fixed buffer of size LEN at address PTR + +``ALLOCA, (ptr, len),'' + output data is placed in an alloca()ed buffer of size LEN pointed + to by PTR + +``MALLOC, (ptr, len),'' + output data is in a malloc()ed buffer of size LEN pointed to by PTR + +``C_STRING_ALLOCA, ptr,'' + equivalent to `ALLOCA (ptr, len_ignored)' on output. + +``C_STRING_MALLOC, ptr,'' + equivalent to `MALLOC (ptr, len_ignored)' on output + +``C_STRING, ptr,'' + equivalent to `DATA, (ptr, strlen (ptr) + 1)' on input + +``LISP_STRING, string,'' + input or output is a Lisp_Object of type string + +``LISP_BUFFER, buffer,'' + output is written to `(point)' in lisp buffer BUFFER + +``LISP_LSTREAM, lstream,'' + input or output is a Lisp_Object of type lstream + +``LISP_OPAQUE, object,'' + input or output is a Lisp_Object of type opaque + + Often, the data is being converted to a '\0'-byte-terminated string, +which is the format required by many external system C APIs. For these +purposes, a source type of `C_STRING' or a sink type of +`C_STRING_ALLOCA' or `C_STRING_MALLOC' is appropriate. Otherwise, we +should try to keep XEmacs '\0'-byte-clean, which means using (ptr, len) +pairs. + + The sinks to be specified must be lvalues, unless they are the lisp +object types `LISP_LSTREAM' or `LISP_BUFFER'. + + For the sink types `ALLOCA' and `C_STRING_ALLOCA', the resulting +text is stored in a stack-allocated buffer, which is automatically +freed on returning from the function. However, the sink types `MALLOC' +and `C_STRING_MALLOC' return `xmalloc()'ed memory. The caller is +responsible for freeing this memory using `xfree()'. + + Note that it doesn't make sense for `LISP_STRING' to be a source for +`TO_INTERNAL_FORMAT' or a sink for `TO_EXTERNAL_FORMAT'. You'll get an +assertion failure if you try. + + +File: internals.info, Node: General Guidelines for Writing Mule-Aware Code, Next: An Example of Mule-Aware Code, Prev: Conversion to and from External Data, Up: Coding for Mule + +8.7.4 General Guidelines for Writing Mule-Aware Code +---------------------------------------------------- + +This section contains some general guidance on how to write Mule-aware +code, as well as some pitfalls you should avoid. + +_Never use `char' and `char *'._ + In XEmacs, the use of `char' and `char *' is almost always a + mistake. If you want to manipulate an Emacs character from "C", + use `Emchar'. If you want to examine a specific octet in the + internal format, use `Bufbyte'. If you want a Lisp-visible + character, use a `Lisp_Object' and `make_char'. If you want a + pointer to move through the internal text, use `Bufbyte *'. Also + note that you almost certainly do not need `Emchar *'. + +_Be careful not to confuse `Charcount', `Bytecount', and `Bufpos'._ + The whole point of using different types is to avoid confusion + about the use of certain variables. Lest this effect be + nullified, you need to be careful about using the right types. + +_Always convert external data_ + It is extremely important to always convert external data, because + XEmacs can crash if unexpected 8bit sequences are copied to its + internal buffers literally. + + This means that when a system function, such as `readdir', returns + a string, you may need to convert it using one of the conversion + macros described in the previous chapter, before passing it + further to Lisp. + + Actually, most of the basic system functions that accept + '\0'-terminated string arguments, like `stat()' and `open()', have + been *encapsulated* so that they are they `always' do internal to + external conversion themselves. This means you must pass + internally encoded data, typically the `XSTRING_DATA' of a + Lisp_String to these functions. This is actually a design bug, + since it unexpectedly changes the semantics of the system + functions. A better design would be to provide separate versions + of these system functions that accepted Lisp_Objects which were + lisp strings in place of their current `char *' arguments. + + int stat_lisp (Lisp_Object path, struct stat *buf); /* Implement me */ + + Also note that many internal functions, such as `make_string', + accept Bufbytes, which removes the need for them to convert the + data they receive. This increases efficiency because that way + external data needs to be decoded only once, when it is read. + After that, it is passed around in internal format. + + +File: internals.info, Node: An Example of Mule-Aware Code, Prev: General Guidelines for Writing Mule-Aware Code, Up: Coding for Mule + +8.7.5 An Example of Mule-Aware Code +----------------------------------- + +As an example of Mule-aware code, we will analyze the `string' +function, which conses up a Lisp string from the character arguments it +receives. Here is the definition, pasted from `alloc.c': + + DEFUN ("string", Fstring, 0, MANY, 0, /* + Concatenate all the argument characters and make the result a string. + */ + (int nargs, Lisp_Object *args)) + { + Bufbyte *storage = alloca_array (Bufbyte, nargs * MAX_EMCHAR_LEN); + Bufbyte *p = storage; + + for (; nargs; nargs--, args++) + { + Lisp_Object lisp_char = *args; + CHECK_CHAR_COERCE_INT (lisp_char); + p += set_charptr_emchar (p, XCHAR (lisp_char)); + } + return make_string (storage, p - storage); + } + + Now we can analyze the source line by line. + + Obviously, string will be as long as there are arguments to the +function. This is why we allocate `MAX_EMCHAR_LEN' * NARGS bytes on +the stack, i.e. the worst-case number of bytes for NARGS `Emchar's to +fit in the string. + + Then, the loop checks that each element is a character, converting +integers in the process. Like many other functions in XEmacs, this +function silently accepts integers where characters are expected, for +historical and compatibility reasons. Unless you know what you are +doing, `CHECK_CHAR' will also suffice. `XCHAR (lisp_char)' extracts +the `Emchar' from the `Lisp_Object', and `set_charptr_emchar' stores it +to storage, increasing `p' in the process. + + Other instructive examples of correct coding under Mule can be found +all over the XEmacs code. For starters, I recommend +`Fnormalize_menu_item_name' in `menubar.c'. After you have understood +this section of the manual and studied the examples, you can proceed +writing new Mule-aware code. + + +File: internals.info, Node: Techniques for XEmacs Developers, Prev: Coding for Mule, Up: Rules When Writing New C Code + +8.8 Techniques for XEmacs Developers +==================================== + +To make a purified XEmacs, do: `make puremacs'. To make a quantified +XEmacs, do: `make quantmacs'. + + You simply can't dump Quantified and Purified images (unless using +the portable dumper). Purify gets confused when xemacs frees memory in +one process that was allocated in a _different_ process on a different +machine!. Run it like so: + temacs -batch -l loadup.el run-temacs XEMACS-ARGS... + + Before you go through the trouble, are you compiling with all +debugging and error-checking off? If not, try that first. Be warned +that while Quantify is directly responsible for quite a few +optimizations which have been made to XEmacs, doing a run which +generates results which can be acted upon is not necessarily a trivial +task. + + Also, if you're still willing to do some runs make sure you configure +with the `--quantify' flag. That will keep Quantify from starting to +record data until after the loadup is completed and will shut off +recording right before it shuts down (which generates enough bogus data +to throw most results off). It also enables three additional elisp +commands: `quantify-start-recording-data', +`quantify-stop-recording-data' and `quantify-clear-data'. + + If you want to make XEmacs faster, target your favorite slow +benchmark, run a profiler like Quantify, `gprof', or `tcov', and figure +out where the cycles are going. In many cases you can localize the +problem (because a particular new feature or even a single patch +elicited it). Don't hesitate to use brute force techniques like a +global counter incremented at strategic places, especially in +combination with other performance indications (_e.g._, degree of +buffer fragmentation into extents). + + Specific projects: + + * Make the garbage collector faster. Figure out how to write an + incremental garbage collector. + + * Write a compiler that takes bytecode and spits out C code. + Unfortunately, you will then need a C compiler and a more fully + developed module system. + + * Speed up redisplay. + + * Speed up syntax highlighting. It was suggested that "maybe moving + some of the syntax highlighting capabilities into C would make a + difference." Wrong idea, I think. When processing one 400kB file + a particular low-level routine was being called 40 _million_ times + simply for _one_ call to `newline-and-indent'. Syntax + highlighting needs to be rewritten to use a reliable, fast parser, + then to trust the pre-parsed structure, and only do + re-highlighting locally to a text change. Modern machines are + fast enough to implement such parsers in Lisp; but no machine will + ever be fast enough to deal with quadratic (or worse) algorithms! + + * Implement tail recursion in Emacs Lisp (hard!). + + Unfortunately, Emacs Lisp is slow, and is going to stay slow. +Function calls in elisp are especially expensive. Iterating over a +long list is going to be 30 times faster implemented in C than in Elisp. + + Heavily used small code fragments need to be fast. The traditional +way to implement such code fragments in C is with macros. But macros +in C are known to be broken. + + Macro arguments that are repeatedly evaluated may suffer from +repeated side effects or suboptimal performance. + + Variable names used in macros may collide with caller's variables, +causing (at least) unwanted compiler warnings. + + In order to solve these problems, and maintain statement semantics, +one should use the `do { ... } while (0)' trick while trying to +reference macro arguments exactly once using local variables. + + Let's take a look at this poor macro definition: + + #define MARK_OBJECT(obj) \ + if (!marked_p (obj)) mark_object (obj), did_mark = 1 + + This macro evaluates its argument twice, and also fails if used like +this: + if (flag) MARK_OBJECT (obj); else do_something(); + + A much better definition is + + #define MARK_OBJECT(obj) do { \ + Lisp_Object mo_obj = (obj); \ + if (!marked_p (mo_obj)) \ + { \ + mark_object (mo_obj); \ + did_mark = 1; \ + } \ + } while (0) + + Notice the elimination of double evaluation by using the local +variable with the obscure name. Writing safe and efficient macros +requires great care. The one problem with macros that cannot be +portably worked around is, since a C block has no value, a macro used +as an expression rather than a statement cannot use the techniques just +described to avoid multiple evaluation. + + In most cases where a macro has function semantics, an inline +function is a better implementation technique. Modern compiler +optimizers tend to inline functions even if they have no `inline' +keyword, and configure magic ensures that the `inline' keyword can be +safely used as an additional compiler hint. Inline functions used in a +single .c files are easy. The function must already be defined to be +`static'. Just add another `inline' keyword to the definition. + + inline static int + heavily_used_small_function (int arg) + { + ... + } + + Inline functions in header files are trickier, because we would like +to make the following optimization if the function is _not_ inlined +(for example, because we're compiling for debugging). We would like the +function to be defined externally exactly once, and each calling +translation unit would create an external reference to the function, +instead of including a definition of the inline function in the object +code of every translation unit that uses it. This optimization is +currently only available for gcc. But you don't have to worry about the +trickiness; just define your inline functions in header files using this +pattern: + + INLINE_HEADER int + i_used_to_be_a_crufty_macro_but_look_at_me_now (int arg); + INLINE_HEADER int + i_used_to_be_a_crufty_macro_but_look_at_me_now (int arg) + { + ... + } + + The declaration right before the definition is to prevent warnings +when compiling with `gcc -Wmissing-declarations'. I consider issuing +this warning for inline functions a gcc bug, but the gcc maintainers +disagree. + + Every header which contains inline functions, either directly by +using `INLINE_HEADER' or indirectly by using `DECLARE_LRECORD' must be +added to `inline.c''s includes to make the optimization described above +work. (Optimization note: if all INLINE_HEADER functions are in fact +inlined in all translation units, then the linker can just discard +`inline.o', since it contains only unreferenced code). + + To get started debugging XEmacs, take a look at the `.gdbinit' and +`.dbxrc' files in the `src' directory. See the section in the XEmacs +FAQ on How to Debug an XEmacs problem with a debugger. + + After making source code changes, run `make check' to ensure that +you haven't introduced any regressions. If you want to make xemacs more +reliable, please improve the test suite in `tests/automated'. + + Did you make sure you didn't introduce any new compiler warnings? + + Before submitting a patch, please try compiling at least once with + + configure --with-mule --use-union-type --error-checking=all + + Here are things to know when you create a new source file: + + * All `.c' files should `#include ' first. Almost all + `.c' files should `#include "lisp.h"' second. + + * Generated header files should be included using the `#include + <...>' syntax, not the `#include "..."' syntax. The generated + headers are: + + `config.h sheap-adjust.h paths.h Emacs.ad.h' + + The basic rule is that you should assume builds using `--srcdir' + and the `#include <...>' syntax needs to be used when the + to-be-included generated file is in a potentially different + directory _at compile time_. The non-obvious C rule is that + `#include "..."' means to search for the included file in the same + directory as the including file, _not_ in the current directory. + Normally this is not a problem but when building with `--srcdir', + `make' will search the `VPATH' for you, while the C compiler knows + nothing about it. + + * Header files should _not_ include `' and `"lisp.h"'. It + is the responsibility of the `.c' files that use it to do so. + + + Here is a checklist of things to do when creating a new lisp object +type named FOO: + + 1. create FOO.h + + 2. create FOO.c + + 3. add definitions of `syms_of_FOO', etc. to `FOO.c' + + 4. add declarations of `syms_of_FOO', etc. to `symsinit.h' + + 5. add calls to `syms_of_FOO', etc. to `emacs.c' + + 6. add definitions of macros like `CHECK_FOO' and `FOOP' to `FOO.h' + + 7. add the new type index to `enum lrecord_type' + + 8. add a DEFINE_LRECORD_IMPLEMENTATION call to `FOO.c' + + 9. add an INIT_LRECORD_IMPLEMENTATION call to `syms_of_FOO.c' + + +File: internals.info, Node: Regression Testing XEmacs, Next: A Summary of the Various XEmacs Modules, Prev: Rules When Writing New C Code, Up: Top + +9 Regression Testing XEmacs +*************************** + +The source directory `tests/automated' contains XEmacs' automated test +suite. The usual way of running all the tests is running `make check' +from the top-level source directory. + + The test suite is unfinished and it's still lacking some essential +features. It is nevertheless recommended that you run the tests to +confirm that XEmacs behaves correctly. + + If you want to run a specific test case, you can do it from the +command-line like this: + + $ xemacs -batch -l test-harness.elc -f batch-test-emacs TEST-FILE + + If something goes wrong, you can run the test suite interactively by +loading `test-harness.el' into a running XEmacs and typing `M-x +test-emacs-test-file RET RET'. You will see a log of passed +and failed tests, which should allow you to investigate the source of +the error and ultimately fix the bug. + + Adding a new test file is trivial: just create a new file here and it +will be run. There is no need to byte-compile any of the files in this +directory--the test-harness will take care of any necessary +byte-compilation. + + Look at the existing test cases for the examples of coding test +cases. It all boils down to your imagination and judicious use of the +macros `Assert', `Check-Error', `Check-Error-Message', and +`Check-Message'. + + Here's a simple example checking case-sensitive and case-insensitive +comparisons from `case-tests.el'. + + (with-temp-buffer + (insert "Test Buffer") + (let ((case-fold-search t)) + (goto-char (point-min)) + (Assert (eq (search-forward "test buffer" nil t) 12)) + (goto-char (point-min)) + (Assert (eq (search-forward "Test buffer" nil t) 12)) + (goto-char (point-min)) + (Assert (eq (search-forward "Test Buffer" nil t) 12)) + + (setq case-fold-search nil) + (goto-char (point-min)) + (Assert (not (search-forward "test buffer" nil t))) + (goto-char (point-min)) + (Assert (not (search-forward "Test buffer" nil t))) + (goto-char (point-min)) + (Assert (eq (search-forward "Test Buffer" nil t) 12)))) + + This example could be inserted in a file in `tests/automated', and +it would be a complete test, automatically executed when you run `make +check' after building XEmacs. More complex tests may require +substantial temporary scaffolding to create the environment that elicits +the bugs, but the top-level Makefile and `test-harness.el' handle the +running and collection of results from the `Assert', `Check-Error', +`Check-Error-Message', and `Check-Message' macros. + + In general, you should avoid using functionality from packages in +your tests, because you can't be sure that everyone will have the +required package. However, if you've got a test that works, by all +means add it. Simply wrap the test in an appropriate test, add a +notice that the test was skipped, and update the `skipped-test-reasons' +hashtable. Here's an example from `syntax-tests.el': + + ;; Test forward-comment at buffer boundaries + (with-temp-buffer + + ;; try to use exactly what you need: featurep, boundp, fboundp + (if (not (fboundp 'c-mode)) + + ;; We should provide a standard function for this boilerplate, + ;; probably called `Skip-Test' -- check for that API with C-h f + (let* ((reason "c-mode unavailable") + (count (gethash reason skipped-test-reasons))) + (puthash reason (if (null count) 1 (1+ count)) + skipped-test-reasons) + (Print-Skip "comment and parse-partial-sexp tests" reason)) + + ;; and here's the test code + (c-mode) + (insert "// comment\n") + (forward-comment -2) + (Assert (eq (point) (point-min))) + (let ((point (point))) + (insert "/* comment */") + (goto-char point) + (forward-comment 2) + (Assert (eq (point) (point-max))) + (parse-partial-sexp point (point-max))))) + + `Skip-Test' is intended for use with features that are normally +present in typical configurations. For truly optional features, or +tests that apply to one of several alternative implementations (eg, to +GTK widgets, but not Athena, Motif, MS Windows, or Carbon), simply +silently omit the test. + + +File: internals.info, Node: A Summary of the Various XEmacs Modules, Next: Allocation of Objects in XEmacs Lisp, Prev: Regression Testing XEmacs, Up: Top + +10 A Summary of the Various XEmacs Modules +****************************************** + +This is accurate as of XEmacs 20.0. + +* Menu: + +* Low-Level Modules:: +* Basic Lisp Modules:: +* Modules for Standard Editing Operations:: +* Editor-Level Control Flow Modules:: +* Modules for the Basic Displayable Lisp Objects:: +* Modules for other Display-Related Lisp Objects:: +* Modules for the Redisplay Mechanism:: +* Modules for Interfacing with the File System:: +* Modules for Other Aspects of the Lisp Interpreter and Object System:: +* Modules for Interfacing with the Operating System:: +* Modules for Interfacing with X Windows:: +* Modules for Internationalization:: +* Modules for Regression Testing:: + + +File: internals.info, Node: Low-Level Modules, Next: Basic Lisp Modules, Up: A Summary of the Various XEmacs Modules + +10.1 Low-Level Modules +====================== + + config.h + + This is automatically generated from `config.h.in' based on the +results of configure tests and user-selected optional features and +contains preprocessor definitions specifying the nature of the +environment in which XEmacs is being compiled. + + paths.h + + This is automatically generated from `paths.h.in' based on supplied +configure values, and allows for non-standard installed configurations +of the XEmacs directories. It's currently broken, though. + + emacs.c + signal.c + + `emacs.c' contains `main()' and other code that performs the most +basic environment initializations and handles shutting down the XEmacs +process (this includes `kill-emacs', the normal way that XEmacs is +exited; `dump-emacs', which is used during the build process to write +out the XEmacs executable; `run-emacs-from-temacs', which can be used +to start XEmacs directly when temacs has finished loading all the Lisp +code; and emergency code to handle crashes [XEmacs tries to auto-save +all files before it crashes]). + + Low-level code that directly interacts with the Unix signal +mechanism, however, is in `signal.c'. Note that this code does not +handle system dependencies in interfacing to signals; that is handled +using the `syssignal.h' header file, described in section J below. + + unexaix.c + unexalpha.c + unexapollo.c + unexconvex.c + unexec.c + unexelf.c + unexelfsgi.c + unexencap.c + unexenix.c + unexfreebsd.c + unexfx2800.c + unexhp9k3.c + unexhp9k800.c + unexmips.c + unexnext.c + unexsol2.c + unexsunos4.c + + These modules contain code dumping out the XEmacs executable on +various different systems. (This process is highly machine-specific and +requires intimate knowledge of the executable format and the memory map +of the process.) Only one of these modules is actually used; this is +chosen by `configure'. + + ecrt0.c + lastfile.c + pre-crt0.c + + These modules are used in conjunction with the dump mechanism. On +some systems, an alternative version of the C startup code (the actual +code that receives control from the operating system when the process is +started, and which calls `main()') is required so that the dumping +process works properly; `crt0.c' provides this. + + `pre-crt0.c' and `lastfile.c' should be the very first and very last +file linked, respectively. (Actually, this is not really true. +`lastfile.c' should be after all Emacs modules whose initialized data +should be made constant, and before all other Emacs files and all +libraries. In particular, the allocation modules `gmalloc.c', +`alloca.c', etc. are normally placed past `lastfile.c', and all of the +files that implement Xt widget classes _must_ be placed after +`lastfile.c' because they contain various structures that must be +statically initialized and into which Xt writes at various times.) +`pre-crt0.c' and `lastfile.c' contain exported symbols that are used to +determine the start and end of XEmacs' initialized data space when +dumping. + + alloca.c + free-hook.c + getpagesize.h + gmalloc.c + malloc.c + mem-limits.h + ralloc.c + vm-limit.c + + These handle basic C allocation of memory. `alloca.c' is an +emulation of the stack allocation function `alloca()' on machines that +lack this. (XEmacs makes extensive use of `alloca()' in its code.) + + `gmalloc.c' and `malloc.c' are two implementations of the standard C +functions `malloc()', `realloc()' and `free()'. They are often used in +place of the standard system-provided `malloc()' because they usually +provide a much faster implementation, at the expense of additional +memory use. `gmalloc.c' is a newer implementation that is much more +memory-efficient for large allocations than `malloc.c', and should +always be preferred if it works. (At one point, `gmalloc.c' didn't work +on some systems where `malloc.c' worked; but this should be fixed now.) + + `ralloc.c' is the "relocating allocator". It provides functions +similar to `malloc()', `realloc()' and `free()' that allocate memory +that can be dynamically relocated in memory. The advantage of this is +that allocated memory can be shuffled around to place all the free +memory at the end of the heap, and the heap can then be shrunk, +releasing the memory back to the operating system. The use of this can +be controlled with the configure option `--rel-alloc'; if enabled, +memory allocated for buffers will be relocatable, so that if a very +large file is visited and the buffer is later killed, the memory can be +released to the operating system. (The disadvantage of this mechanism +is that it can be very slow. On systems with the `mmap()' system call, +the XEmacs version of `ralloc.c' uses this to move memory around +without actually having to block-copy it, which can speed things up; +but it can still cause noticeable performance degradation.) + + `free-hook.c' contains some debugging functions for checking for +invalid arguments to `free()'. + + `vm-limit.c' contains some functions that warn the user when memory +is getting low. These are callback functions that are called by +`gmalloc.c' and `malloc.c' at appropriate times. + + `getpagesize.h' provides a uniform interface for retrieving the size +of a page in virtual memory. `mem-limits.h' provides a uniform +interface for retrieving the total amount of available virtual memory. +Both are similar in spirit to the `sys*.h' files described in section +J, below. + + blocktype.c + blocktype.h + dynarr.c + + These implement a couple of basic C data types to facilitate memory +allocation. The `Blocktype' type efficiently manages the allocation of +fixed-size blocks by minimizing the number of times that `malloc()' and +`free()' are called. It allocates memory in large chunks, subdivides +the chunks into blocks of the proper size, and returns the blocks as +requested. When blocks are freed, they are placed onto a linked list, +so they can be efficiently reused. This data type is not much used in +XEmacs currently, because it's a fairly new addition. + + The `Dynarr' type implements a "dynamic array", which is similar to +a standard C array but has no fixed limit on the number of elements it +can contain. Dynamic arrays can hold elements of any type, and when +you add a new element, the array automatically resizes itself if it +isn't big enough. Dynarrs are extensively used in the redisplay +mechanism. + + inline.c + + This module is used in connection with inline functions (available in +some compilers). Often, inline functions need to have a corresponding +non-inline function that does the same thing. This module is where they +reside. It contains no actual code, but defines some special flags that +cause inline functions defined in header files to be rendered as actual +functions. It then includes all header files that contain any inline +function definitions, so that each one gets a real function equivalent. + + debug.c + debug.h + + These functions provide a system for doing internal consistency +checks during code development. This system is not currently used; +instead the simpler `assert()' macro is used along with the various +checks provided by the `--error-check-*' configuration options. + + universe.h + + This is not currently used. + + +File: internals.info, Node: Basic Lisp Modules, Next: Modules for Standard Editing Operations, Prev: Low-Level Modules, Up: A Summary of the Various XEmacs Modules + +10.2 Basic Lisp Modules +======================= + + lisp-disunion.h + lisp-union.h + lisp.h + lrecord.h + symsinit.h + + These are the basic header files for all XEmacs modules. Each module +includes `lisp.h', which brings the other header files in. `lisp.h' +contains the definitions of the structures and extractor and +constructor macros for the basic Lisp objects and various other basic +definitions for the Lisp environment, as well as some general-purpose +definitions (e.g. `min()' and `max()'). `lisp.h' includes either +`lisp-disunion.h' or `lisp-union.h', depending on whether +`USE_UNION_TYPE' is defined. These files define the typedef of the +Lisp object itself (as described above) and the low-level macros that +hide the actual implementation of the Lisp object. All extractor and +constructor macros for particular types of Lisp objects are defined in +terms of these low-level macros. + + As a general rule, all typedefs should go into the typedefs section +of `lisp.h' rather than into a module-specific header file even if the +structure is defined elsewhere. This allows function prototypes that +use the typedef to be placed into other header files. Forward structure +declarations (i.e. a simple declaration like `struct foo;' where the +structure itself is defined elsewhere) should be placed into the +typedefs section as necessary. + + `lrecord.h' contains the basic structures and macros that implement +all record-type Lisp objects--i.e. all objects whose type is a field in +their C structure, which includes all objects except the few most basic +ones. + + `lisp.h' contains prototypes for most of the exported functions in +the various modules. Lisp primitives defined using `DEFUN' that need +to be called by C code should be declared using `EXFUN'. Other +function prototypes should be placed either into the appropriate +section of `lisp.h', or into a module-specific header file, depending +on how general-purpose the function is and whether it has +special-purpose argument types requiring definitions not in `lisp.h'.) +All initialization functions are prototyped in `symsinit.h'. + + alloc.c + + The large module `alloc.c' implements all of the basic allocation and +garbage collection for Lisp objects. The most commonly used Lisp +objects are allocated in chunks, similar to the Blocktype data type +described above; others are allocated in individually `malloc()'ed +blocks. This module provides the foundation on which all other aspects +of the Lisp environment sit, and is the first module initialized at +startup. + + Note that `alloc.c' provides a series of generic functions that are +not dependent on any particular object type, and interfaces to +particular types of objects using a standardized interface of +type-specific methods. This scheme is a fundamental principle of +object-oriented programming and is heavily used throughout XEmacs. The +great advantage of this is that it allows for a clean separation of +functionality into different modules--new classes of Lisp objects, new +event interfaces, new device types, new stream interfaces, etc. can be +added transparently without affecting code anywhere else in XEmacs. +Because the different subsystems are divided into general and specific +code, adding a new subtype within a subsystem will in general not +require changes to the generic subsystem code or affect any of the other +subtypes in the subsystem; this provides a great deal of robustness to +the XEmacs code. + + eval.c + backtrace.h + + This module contains all of the functions to handle the flow of +control. This includes the mechanisms of defining functions, calling +functions, traversing stack frames, and binding variables; the control +primitives and other special forms such as `while', `if', `eval', +`let', `and', `or', `progn', etc.; handling of non-local exits, +unwind-protects, and exception handlers; entering the debugger; methods +for the subr Lisp object type; etc. It does _not_ include the `read' +function, the `print' function, or the handling of symbols and obarrays. + + `backtrace.h' contains some structures related to stack frames and +the flow of control. + + lread.c + + This module implements the Lisp reader and the `read' function, +which converts text into Lisp objects, according to the read syntax of +the objects, as described above. This is similar to the parser that is +a part of all compilers. + + print.c + + This module implements the Lisp print mechanism and the `print' +function and related functions. This is the inverse of the Lisp reader +- it converts Lisp objects to a printed, textual representation. +(Hopefully something that can be read back in using `read' to get an +equivalent object.) + + general.c + symbols.c + symeval.h + + `symbols.c' implements the handling of symbols, obarrays, and +retrieving the values of symbols. Much of the code is devoted to +handling the special "symbol-value-magic" objects that define special +types of variables--this includes buffer-local variables, variable +aliases, variables that forward into C variables, etc. This module is +initialized extremely early (right after `alloc.c'), because it is here +that the basic symbols `t' and `nil' are created, and those symbols are +used everywhere throughout XEmacs. + + `symeval.h' contains the definitions of symbol structures and the +`DEFVAR_LISP()' and related macros for declaring variables. + + data.c + floatfns.c + fns.c + + These modules implement the methods and standard Lisp primitives for +all the basic Lisp object types other than symbols (which are described +above). `data.c' contains all the predicates (primitives that return +whether an object is of a particular type); the integer arithmetic +functions; and the basic accessor and mutator primitives for the various +object types. `fns.c' contains all the standard predicates for working +with sequences (where, abstractly speaking, a sequence is an ordered set +of objects, and can be represented by a list, string, vector, or +bit-vector); it also contains `equal', perhaps on the grounds that bulk +of the operation of `equal' is comparing sequences. `floatfns.c' +contains methods and primitives for floats and floating-point +arithmetic. + + bytecode.c + bytecode.h + + `bytecode.c' implements the byte-code interpreter and +compiled-function objects, and `bytecode.h' contains associated +structures. Note that the byte-code _compiler_ is written in Lisp. + + +File: internals.info, Node: Modules for Standard Editing Operations, Next: Editor-Level Control Flow Modules, Prev: Basic Lisp Modules, Up: A Summary of the Various XEmacs Modules + +10.3 Modules for Standard Editing Operations +============================================ + + buffer.c + buffer.h + bufslots.h + + `buffer.c' implements the "buffer" Lisp object type. This includes +functions that create and destroy buffers; retrieve buffers by name or +by other properties; manipulate lists of buffers (remember that buffers +are permanent objects and stored in various ordered lists); retrieve or +change buffer properties; etc. It also contains the definitions of all +the built-in buffer-local variables (which can be viewed as buffer +properties). It does _not_ contain code to manipulate buffer-local +variables (that's in `symbols.c', described above); or code to +manipulate the text in a buffer. + + `buffer.h' defines the structures associated with a buffer and the +various macros for retrieving text from a buffer and special buffer +positions (e.g. `point', the default location for text insertion). It +also contains macros for working with buffer positions and converting +between their representations as character offsets and as byte offsets +(under MULE, they are different, because characters can be multi-byte). +It is one of the largest header files. + + `bufslots.h' defines the fields in the buffer structure that +correspond to the built-in buffer-local variables. It is its own +header file because it is included many times in `buffer.c', as a way +of iterating over all the built-in buffer-local variables. + + insdel.c + insdel.h + + `insdel.c' contains low-level functions for inserting and deleting +text in a buffer, keeping track of changed regions for use by +redisplay, and calling any before-change and after-change functions +that may have been registered for the buffer. It also contains the +actual functions that convert between byte offsets and character +offsets. + + `insdel.h' contains associated headers. + + marker.c + + This module implements the "marker" Lisp object type, which +conceptually is a pointer to a text position in a buffer that moves +around as text is inserted and deleted, so as to remain in the same +relative position. This module doesn't actually move the markers around +- that's handled in `insdel.c'. This module just creates them and +implements the primitives for working with them. As markers are simple +objects, this does not entail much. + + Note that the standard arithmetic primitives (e.g. `+') accept +markers in place of integers and automatically substitute the value of +`marker-position' for the marker, i.e. an integer describing the +current buffer position of the marker. + + extents.c + extents.h + + This module implements the "extent" Lisp object type, which is like +a marker that works over a range of text rather than a single position. +Extents are also much more complex and powerful than markers and have a +more efficient (and more algorithmically complex) implementation. The +implementation is described in detail in comments in `extents.c'. + + The code in `extents.c' works closely with `insdel.c' so that +extents are properly moved around as text is inserted and deleted. +There is also code in `extents.c' that provides information needed by +the redisplay mechanism for efficient operation. (Remember that extents +can have display properties that affect [sometimes drastically, as in +the `invisible' property] the display of the text they cover.) + + editfns.c + + `editfns.c' contains the standard Lisp primitives for working with a +buffer's text, and calls the low-level functions in `insdel.c'. It +also contains primitives for working with `point' (the default buffer +insertion location). + + `editfns.c' also contains functions for retrieving various +characteristics from the external environment: the current time, the +process ID of the running XEmacs process, the name of the user who ran +this XEmacs process, etc. It's not clear why this code is in +`editfns.c'. + + callint.c + cmds.c + commands.h + + These modules implement the basic "interactive" commands, i.e. +user-callable functions. Commands, as opposed to other functions, have +special ways of getting their parameters interactively (by querying the +user), as opposed to having them passed in a normal function +invocation. Many commands are not really meant to be called from other +Lisp functions, because they modify global state in a way that's often +undesired as part of other Lisp functions. + + `callint.c' implements the mechanism for querying the user for +parameters and calling interactive commands. The bulk of this module is +code that parses the interactive spec that is supplied with an +interactive command. + + `cmds.c' implements the basic, most commonly used editing commands: +commands to move around the current buffer and insert and delete +characters. These commands are implemented using the Lisp primitives +defined in `editfns.c'. + + `commands.h' contains associated structure definitions and +prototypes. + + regex.c + regex.h + search.c + + `search.c' implements the Lisp primitives for searching for text in +a buffer, and some of the low-level algorithms for doing this. In +particular, the fast fixed-string Boyer-Moore search algorithm is +implemented in `search.c'. The low-level algorithms for doing +regular-expression searching, however, are implemented in `regex.c' and +`regex.h'. These two modules are largely independent of XEmacs, and +are similar to (and based upon) the regular-expression routines used in +`grep' and other GNU utilities. + + doprnt.c + + `doprnt.c' implements formatted-string processing, similar to +`printf()' command in C. + + undo.c + + This module implements the undo mechanism for tracking buffer +changes. Most of this could be implemented in Lisp. + + +File: internals.info, Node: Editor-Level Control Flow Modules, Next: Modules for the Basic Displayable Lisp Objects, Prev: Modules for Standard Editing Operations, Up: A Summary of the Various XEmacs Modules + +10.4 Editor-Level Control Flow Modules +====================================== + + event-Xt.c + event-msw.c + event-stream.c + event-tty.c + events-mod.h + gpmevent.c + gpmevent.h + events.c + events.h + + These implement the handling of events (user input and other system +notifications). + + `events.c' and `events.h' define the "event" Lisp object type and +primitives for manipulating it. + + `event-stream.c' implements the basic functions for working with +event queues, dispatching an event by looking it up in relevant keymaps +and such, and handling timeouts; this includes the primitives +`next-event' and `dispatch-event', as well as related primitives such +as `sit-for', `sleep-for', and `accept-process-output'. +(`event-stream.c' is one of the hairiest and trickiest modules in +XEmacs. Beware! You can easily mess things up here.) + + `event-Xt.c' and `event-tty.c' implement the low-level interfaces +onto retrieving events from Xt (the X toolkit) and from TTY's (using +`read()' and `select()'), respectively. The event interface enforces a +clean separation between the specific code for interfacing with the +operating system and the generic code for working with events, by +defining an API of basic, low-level event methods; `event-Xt.c' and +`event-tty.c' are two different implementations of this API. To add +support for a new operating system (e.g. NeXTstep), one merely needs to +provide another implementation of those API functions. + + Note that the choice of whether to use `event-Xt.c' or `event-tty.c' +is made at compile time! Or at the very latest, it is made at startup +time. `event-Xt.c' handles events for _both_ X and TTY frames; +`event-tty.c' is only used when X support is not compiled into XEmacs. +The reason for this is that there is only one event loop in XEmacs: +thus, it needs to be able to receive events from all different kinds of +frames. + + keymap.c + keymap.h + + `keymap.c' and `keymap.h' define the "keymap" Lisp object type and +associated methods and primitives. (Remember that keymaps are objects +that associate event descriptions with functions to be called to +"execute" those events; `dispatch-event' looks up events in the +relevant keymaps.) + + cmdloop.c + + `cmdloop.c' contains functions that implement the actual editor +command loop--i.e. the event loop that cyclically retrieves and +dispatches events. This code is also rather tricky, just like +`event-stream.c'. + + macros.c + macros.h + + These two modules contain the basic code for defining keyboard +macros. These functions don't actually do much; most of the code that +handles keyboard macros is mixed in with the event-handling code in +`event-stream.c'. + + minibuf.c + + This contains some miscellaneous code related to the minibuffer +(most of the minibuffer code was moved into Lisp by Richard Mlynarik). +This includes the primitives for completion (although filename +completion is in `dired.c'), the lowest-level interface to the +minibuffer (if the command loop were cleaned up, this too could be in +Lisp), and code for dealing with the echo area (this, too, was mostly +moved into Lisp, and the only code remaining is code to call out to +Lisp or provide simple bootstrapping implementations early in temacs, +before the echo-area Lisp code is loaded). + + +File: internals.info, Node: Modules for the Basic Displayable Lisp Objects, Next: Modules for other Display-Related Lisp Objects, Prev: Editor-Level Control Flow Modules, Up: A Summary of the Various XEmacs Modules + +10.5 Modules for the Basic Displayable Lisp Objects +=================================================== + + console-msw.c + console-msw.h + console-stream.c + console-stream.h + console-tty.c + console-tty.h + console-x.c + console-x.h + console.c + console.h + + These modules implement the "console" Lisp object type. A console +contains multiple display devices, but only one keyboard and mouse. +Most of the time, a console will contain exactly one device. + + Consoles are the top of a lisp object inclusion hierarchy. Consoles +contain devices, which contain frames, which contain windows. + + device-msw.c + device-tty.c + device-x.c + device.c + device.h + + These modules implement the "device" Lisp object type. This +abstracts a particular screen or connection on which frames are +displayed. As with Lisp objects, event interfaces, and other +subsystems, the device code is separated into a generic component that +contains a standardized interface (in the form of a set of methods) onto +particular device types. + + The device subsystem defines all the methods and provides method +services for not only device operations but also for the frame, window, +menubar, scrollbar, toolbar, and other displayable-object subsystems. +The reason for this is that all of these subsystems have the same +subtypes (X, TTY, NeXTstep, Microsoft Windows, etc.) as devices do. + + frame-msw.c + frame-tty.c + frame-x.c + frame.c + frame.h + + Each device contains one or more frames in which objects (e.g. text) +are displayed. A frame corresponds to a window in the window system; +usually this is a top-level window but it could potentially be one of a +number of overlapping child windows within a top-level window, using the +MDI (Multiple Document Interface) protocol in Microsoft Windows or a +similar scheme. + + The `frame-*' files implement the "frame" Lisp object type and +provide the generic and device-type-specific operations on frames (e.g. +raising, lowering, resizing, moving, etc.). + + window.c + window.h + + Each frame consists of one or more non-overlapping "windows" (better +known as "panes" in standard window-system terminology) in which a +buffer's text can be displayed. Windows can also have scrollbars +displayed around their edges. + + `window.c' and `window.h' implement the "window" Lisp object type +and provide code to manage windows. Since windows have no associated +resources in the window system (the window system knows only about the +frame; no child windows or anything are used for XEmacs windows), there +is no device-type-specific code here; all of that code is part of the +redisplay mechanism or the code for particular object types such as +scrollbars. + + +File: internals.info, Node: Modules for other Display-Related Lisp Objects, Next: Modules for the Redisplay Mechanism, Prev: Modules for the Basic Displayable Lisp Objects, Up: A Summary of the Various XEmacs Modules + +10.6 Modules for other Display-Related Lisp Objects +=================================================== + + faces.c + faces.h + + bitmaps.h + glyphs-eimage.c + glyphs-msw.c + glyphs-msw.h + glyphs-widget.c + glyphs-x.c + glyphs-x.h + glyphs.c + glyphs.h + + objects-msw.c + objects-msw.h + objects-tty.c + objects-tty.h + objects-x.c + objects-x.h + objects.c + objects.h + + menubar-msw.c + menubar-msw.h + menubar-x.c + menubar.c + menubar.h + + scrollbar-msw.c + scrollbar-msw.h + scrollbar-x.c + scrollbar-x.h + scrollbar.c + scrollbar.h + + toolbar-msw.c + toolbar-x.c + toolbar.c + toolbar.h + + font-lock.c + + This file provides C support for syntax highlighting--i.e. +highlighting different syntactic constructs of a source file in +different colors, for easy reading. The C support is provided so that +this is fast. + + As of 21.4.10, bugs introduced at the very end of the 21.2 series in +the "syntax properties" code were fixed, and highlighting is acceptably +quick again. However, presumably more improvements are possible, and +the places to look are probably here, in the defun-traversing code, and +in `syntax.c', in the comment-traversing code. + + dgif_lib.c + gif_err.c + gif_lib.h + gifalloc.c + + These modules decode GIF-format image files, for use with glyphs. +These files were removed due to Unisys patent infringement concerns. + + +File: internals.info, Node: Modules for the Redisplay Mechanism, Next: Modules for Interfacing with the File System, Prev: Modules for other Display-Related Lisp Objects, Up: A Summary of the Various XEmacs Modules + +10.7 Modules for the Redisplay Mechanism +======================================== + + redisplay-output.c + redisplay-msw.c + redisplay-tty.c + redisplay-x.c + redisplay.c + redisplay.h + + These files provide the redisplay mechanism. As with many other +subsystems in XEmacs, there is a clean separation between the general +and device-specific support. + + `redisplay.c' contains the bulk of the redisplay engine. These +functions update the redisplay structures (which describe how the screen +is to appear) to reflect any changes made to the state of any +displayable objects (buffer, frame, window, etc.) since the last time +that redisplay was called. These functions are highly optimized to +avoid doing more work than necessary (since redisplay is called +extremely often and is potentially a huge time sink), and depend heavily +on notifications from the objects themselves that changes have occurred, +so that redisplay doesn't explicitly have to check each possible object. +The redisplay mechanism also contains a great deal of caching to further +speed things up; some of this caching is contained within the various +displayable objects. + + `redisplay-output.c' goes through the redisplay structures and +converts them into calls to device-specific methods to actually output +the screen changes. + + `redisplay-x.c' and `redisplay-tty.c' are two implementations of +these redisplay output methods, for X frames and TTY frames, +respectively. + + indent.c + + This module contains various functions and Lisp primitives for +converting between buffer positions and screen positions. These +functions call the redisplay mechanism to do most of the work, and then +examine the redisplay structures to get the necessary information. This +module needs work. + + termcap.c + terminfo.c + tparam.c + + These files contain functions for working with the termcap +(BSD-style) and terminfo (System V style) databases of terminal +capabilities and escape sequences, used when XEmacs is displaying in a +TTY. + + cm.c + cm.h + + These files provide some miscellaneous TTY-output functions and +should probably be merged into `redisplay-tty.c'. + + +File: internals.info, Node: Modules for Interfacing with the File System, Next: Modules for Other Aspects of the Lisp Interpreter and Object System, Prev: Modules for the Redisplay Mechanism, Up: A Summary of the Various XEmacs Modules + +10.8 Modules for Interfacing with the File System +================================================= + + lstream.c + lstream.h + + These modules implement the "stream" Lisp object type. This is an +internal-only Lisp object that implements a generic buffering stream. +The idea is to provide a uniform interface onto all sources and sinks of +data, including file descriptors, stdio streams, chunks of memory, Lisp +buffers, Lisp strings, etc. That way, I/O functions can be written to +the stream interface and can transparently handle all possible sources +and sinks. (For example, the `read' function can read data from a +file, a string, a buffer, or even a function that is called repeatedly +to return data, without worrying about where the data is coming from or +what-size chunks it is returned in.) + + Note that in the C code, streams are called "lstreams" (for "Lisp +streams") to distinguish them from other kinds of streams, e.g. stdio +streams and C++ I/O streams. + + Similar to other subsystems in XEmacs, lstreams are separated into +generic functions and a set of methods for the different types of +lstreams. `lstream.c' provides implementations of many different types +of streams; others are provided, e.g., in `file-coding.c'. + + fileio.c + + This implements the basic primitives for interfacing with the file +system. This includes primitives for reading files into buffers, +writing buffers into files, checking for the presence or accessibility +of files, canonicalizing file names, etc. Note that these primitives +are usually not invoked directly by the user: There is a great deal of +higher-level Lisp code that implements the user commands such as +`find-file' and `save-buffer'. This is similar to the distinction +between the lower-level primitives in `editfns.c' and the higher-level +user commands in `commands.c' and `simple.el'. + + filelock.c + + This file provides functions for detecting clashes between different +processes (e.g. XEmacs and some external process, or two different +XEmacs processes) modifying the same file. (XEmacs can optionally use +the `lock/' subdirectory to provide a form of "locking" between +different XEmacs processes.) This module is also used by the low-level +functions in `insdel.c' to ensure that, if the first modification is +being made to a buffer whose corresponding file has been externally +modified, the user is made aware of this so that the buffer can be +synched up with the external changes if necessary. + + filemode.c + + This file provides some miscellaneous functions that construct a +`rwxr-xr-x'-type permissions string (as might appear in an `ls'-style +directory listing) given the information returned by the `stat()' +system call. + + dired.c + ndir.h + + These files implement the XEmacs interface to directory searching. +This includes a number of primitives for determining the files in a +directory and for doing filename completion. (Remember that generic +completion is handled by a different mechanism, in `minibuf.c'.) + + `ndir.h' is a header file used for the directory-searching emulation +functions provided in `sysdep.c' (see section J below), for systems +that don't provide any directory-searching functions. (On those +systems, directories can be read directly as files, and parsed.) + + realpath.c + + This file provides an implementation of the `realpath()' function +for expanding symbolic links, on systems that don't implement it or have +a broken implementation. + + +File: internals.info, Node: Modules for Other Aspects of the Lisp Interpreter and Object System, Next: Modules for Interfacing with the Operating System, Prev: Modules for Interfacing with the File System, Up: A Summary of the Various XEmacs Modules + +10.9 Modules for Other Aspects of the Lisp Interpreter and Object System +======================================================================== + + elhash.c + elhash.h + hash.c + hash.h + + These files provide two implementations of hash tables. Files +`hash.c' and `hash.h' provide a generic C implementation of hash tables +which can stand independently of XEmacs. Files `elhash.c' and +`elhash.h' provide a separate implementation of hash tables that can +store only Lisp objects, and knows about Lispy things like garbage +collection, and implement the "hash-table" Lisp object type. + + specifier.c + specifier.h + + This module implements the "specifier" Lisp object type. This is +primarily used for displayable properties, and allows for values that +are specific to a particular buffer, window, frame, device, or device +class, as well as a default value existing. This is used, for example, +to control the height of the horizontal scrollbar or the appearance of +the `default', `bold', or other faces. The specifier object consists +of a number of specifications, each of which maps from a buffer, +window, etc. to a value. The function `specifier-instance' looks up a +value given a window (from which a buffer, frame, and device can be +derived). + + chartab.c + chartab.h + casetab.c + + `chartab.c' and `chartab.h' implement the "char table" Lisp object +type, which maps from characters or certain sorts of character ranges +to Lisp objects. The implementation of this object type is optimized +for the internal representation of characters. Char tables come in +different types, which affect the allowed object types to which a +character can be mapped and also dictate certain other properties of +the char table. + + `casetab.c' implements one sort of char table, the "case table", +which maps characters to other characters of possibly different case. +These are used by XEmacs to implement case-changing primitives and to +do case-insensitive searching. + + syntax.c + syntax.h + + This module implements "syntax tables", another sort of char table +that maps characters into syntax classes that define the syntax of these +characters (e.g. a parenthesis belongs to a class of `open' characters +that have corresponding `close' characters and can be nested). This +module also implements the Lisp "scanner", a set of primitives for +scanning over text based on syntax tables. This is used, for example, +to find the matching parenthesis in a command such as `forward-sexp', +and by `font-lock.c' to locate quoted strings, comments, etc. + + Syntax codes are implemented as bitfields in an int. Bits 0-6 +contain the syntax code itself, bit 7 is a special prefix flag used for +Lisp, and bits 16-23 contain comment syntax flags. From the Lisp +programmer's point of view, there are 11 flags: 2 styles X 2 characters +X {start, end} flags for two-character comment delimiters, 2 style +flags for one-character comment delimiters, and the prefix flag. + + Internally, however, the characters used in multi-character +delimiters will have non-comment-character syntax classes (_e.g._, the +`/' in C's `/*' comment-start delimiter has "punctuation" (here meaning +"operator-like") class in C modes). Thus in a mixed comment style, +such as C++'s `//' to end of line, is represented by giving `/' the +"punctuation" class and the "style b first character of start sequence" +and "style b second character of start sequence" flags. The fact that +class is _not_ punctuation allows the syntax scanner to recognize that +this is a multi-character delimiter. The `newline' character is given +(single-character) "comment-end" _class_ and the "style b first +character of end sequence" _flag_. The "comment-end" class allows the +scanner to determine that no second character is needed to terminate +the comment. + + There used to be a syntax class `Sextword'. A character of +`Sextword' class is a word-constituent but a word boundary may exist +between two such characters. Ken'ichi HANDA explains +the purpose of the Sextword syntax category: + + Japanese words are not separated by spaces, which makes finding + word boundaries very difficult. Theoretically it's impossible + without using natural language processing techniques. But, by + defining pseudo-words as below (much simplified for letting you + understand it easily) for Japanese, we can have a convenient + forward-word function for Japanese. + + A Japanese word is a sequence of characters that consists of + zero or more Kanji characters followed by zero or more + Hiragana characters. + + Then, the problem is that now we can't say that a sequence of + word-constituents makes up a word. For instance, both Hiragana "A" + and Kanji "KAN" are word-constituents but the sequence of these two + letters can't be a single word. + + So, we introduced Sextword for Japanese letters. + + There seems to have been some controversy about this category, as it +has been removed, readded, and removed again. Currently neither GNU +Emacs (21.3.99) nor XEmacs (21.5.17) seems to use it. + + casefiddle.c + + This module implements various Lisp primitives for upcasing, +downcasing and capitalizing strings or regions of buffers. + + rangetab.c + + This module implements the "range table" Lisp object type, which +provides for a mapping from ranges of integers to arbitrary Lisp +objects. + + opaque.c + opaque.h + + This module implements the "opaque" Lisp object type, an +internal-only Lisp object that encapsulates an arbitrary block of memory +so that it can be managed by the Lisp allocation system. To create an +opaque object, you call `make_opaque()', passing a pointer to a block +of memory. An object is created that is big enough to hold the memory, +which is copied into the object's storage. The object will then stick +around as long as you keep pointers to it, after which it will be +automatically reclaimed. + + Opaque objects can also have an arbitrary "mark method" associated +with them, in case the block of memory contains other Lisp objects that +need to be marked for garbage-collection purposes. (If you need other +object methods, such as a finalize method, you should just go ahead and +create a new Lisp object type--it's not hard.) + + abbrev.c + + This function provides a few primitives for doing dynamic +abbreviation expansion. In XEmacs, most of the code for this has been +moved into Lisp. Some C code remains for speed and because the +primitive `self-insert-command' (which is executed for all +self-inserting characters) hooks into the abbrev mechanism. +(`self-insert-command' is itself in C only for speed.) + + doc.c + + This function provides primitives for retrieving the documentation +strings of functions and variables. These documentation strings contain +certain special markers that get dynamically expanded (e.g. a +reverse-lookup is performed on some named functions to retrieve their +current key bindings). Some documentation strings (in particular, for +the built-in primitives and pre-loaded Lisp functions) are stored +externally in a file `DOC' in the `lib-src/' directory and need to be +fetched from that file. (Part of the build stage involves building this +file, and another part involves constructing an index for this file and +embedding it into the executable, so that the functions in `doc.c' do +not have to search the entire `DOC' file to find the appropriate +documentation string.) + + md5.c + + This function provides a Lisp primitive that implements the MD5 +secure hashing scheme, used to create a large hash value of a string of +data such that the data cannot be derived from the hash value. This is +used for various security applications on the Internet. + + +File: internals.info, Node: Modules for Interfacing with the Operating System, Next: Modules for Interfacing with X Windows, Prev: Modules for Other Aspects of the Lisp Interpreter and Object System, Up: A Summary of the Various XEmacs Modules + +10.10 Modules for Interfacing with the Operating System +======================================================= + + callproc.c + process.c + process.h + + These modules allow XEmacs to spawn and communicate with subprocesses +and network connections. + + `callproc.c' implements (through the `call-process' primitive) what +are called "synchronous subprocesses". This means that XEmacs runs a +program, waits till it's done, and retrieves its output. A typical +example might be calling the `ls' program to get a directory listing. + + `process.c' and `process.h' implement "asynchronous subprocesses". +This means that XEmacs starts a program and then continues normally, +not waiting for the process to finish. Data can be sent to the process +or retrieved from it as it's running. This is used for the `shell' +command (which provides a front end onto a shell program such as +`csh'), the mail and news readers implemented in XEmacs, etc. The +result of calling `start-process' to start a subprocess is a process +object, a particular kind of object used to communicate with the +subprocess. You can send data to the process by passing the process +object and the data to `send-process', and you can specify what happens +to data retrieved from the process by setting properties of the process +object. (When the process sends data, XEmacs receives a process event, +which says that there is data ready. When `dispatch-event' is called +on this event, it reads the data from the process and does something +with it, as specified by the process object's properties. Typically, +this means inserting the data into a buffer or calling a function.) +Another property of the process object is called the "sentinel", which +is a function that is called when the process terminates. + + Process objects are also used for network connections (connections +to a process running on another machine). Network connections are +started with `open-network-stream' but otherwise work just like +subprocesses. + + sysdep.c + sysdep.h + + These modules implement most of the low-level, messy operating-system +interface code. This includes various device control (ioctl) operations +for file descriptors, TTY's, pseudo-terminals, etc. (usually this stuff +is fairly system-dependent; thus the name of this module), and emulation +of standard library functions and system calls on systems that don't +provide them or have broken versions. + + sysdir.h + sysfile.h + sysfloat.h + sysproc.h + syspwd.h + syssignal.h + systime.h + systty.h + syswait.h + + These header files provide consistent interfaces onto +system-dependent header files and system calls. The idea is that, +instead of including a standard header file like `' (which +may or may not exist on various systems) or having to worry about +whether all system provide a particular preprocessor constant, or +having to deal with the four different paradigms for manipulating +signals, you just include the appropriate `sys*.h' header file, which +includes all the right system header files, defines and missing +preprocessor constants, provides a uniform interface onto system calls, +etc. + + `sysdir.h' provides a uniform interface onto directory-querying +functions. (In some cases, this is in conjunction with emulation +functions in `sysdep.c'.) + + `sysfile.h' includes all the necessary header files for standard +system calls (e.g. `read()'), ensures that all necessary `open()' and +`stat()' preprocessor constants are defined, and possibly (usually) +substitutes sugared versions of `read()', `write()', etc. that +automatically restart interrupted I/O operations. + + `sysfloat.h' includes the necessary header files for floating-point +operations. + + `sysproc.h' includes the necessary header files for calling +`select()', `fork()', `execve()', socket operations, and the like, and +ensures that the `FD_*()' macros for descriptor-set manipulations are +available. + + `syspwd.h' includes the necessary header files for obtaining +information from `/etc/passwd' (the functions are emulated under VMS). + + `syssignal.h' includes the necessary header files for +signal-handling and provides a uniform interface onto the different +signal-handling and signal-blocking paradigms. + + `systime.h' includes the necessary header files and provides uniform +interfaces for retrieving the time of day, setting file +access/modification times, getting the amount of time used by the XEmacs +process, etc. + + `systty.h' buffers against the infinitude of different ways of +controlling TTY's. + + `syswait.h' provides a uniform way of retrieving the exit status +from a `wait()'ed-on process (some systems use a union, others use an +int). + + hpplay.c + libsst.c + libsst.h + libst.h + linuxplay.c + nas.c + sgiplay.c + sound.c + sunplay.c + + These files implement the ability to play various sounds on some +types of computers. You have to configure your XEmacs with sound +support in order to get this capability. + + `sound.c' provides the generic interface. It implements various +Lisp primitives and variables that let you specify which sounds should +be played in certain conditions. (The conditions are identified by +symbols, which are passed to `ding' to make a sound. Various standard +functions call this function at certain times; if sound support does +not exist, a simple beep results. + + `sgiplay.c', `sunplay.c', `hpplay.c', and `linuxplay.c' interface to +the machine's speaker for various different kind of machines. This is +called "native" sound. + + `nas.c' interfaces to a computer somewhere else on the network using +the NAS (Network Audio Server) protocol, playing sounds on that +machine. This allows you to run XEmacs on a remote machine, with its +display set to your local machine, and have the sounds be made on your +local machine, provided that you have a NAS server running on your local +machine. + + `libsst.c', `libsst.h', and `libst.h' provide some additional +functions for playing sound on a Sun SPARC but are not currently in use. + + tooltalk.c + tooltalk.h + + These two modules implement an interface to the ToolTalk protocol, +which is an interprocess communication protocol implemented on some +versions of Unix. ToolTalk is a high-level protocol that allows +processes to register themselves as providers of particular services; +other processes can then request a service without knowing or caring +exactly who is providing the service. It is similar in spirit to the +DDE protocol provided under Microsoft Windows. ToolTalk is a part of +the new CDE (Common Desktop Environment) specification and is used to +connect the parts of the SPARCWorks development environment. + + getloadavg.c + + This module provides the ability to retrieve the system's current +load average. (The way to do this is highly system-specific, +unfortunately, and requires a lot of special-case code.) + + sunpro.c + + This module provides a small amount of code used internally at Sun to +keep statistics on the usage of XEmacs. + + broken-sun.h + strcmp.c + strcpy.c + sunOS-fix.c + + These files provide replacement functions and prototypes to fix +numerous bugs in early releases of SunOS 4.1. + + hftctl.c + + This module provides some terminal-control code necessary on +versions of AIX prior to 4.1. + + +File: internals.info, Node: Modules for Interfacing with X Windows, Next: Modules for Internationalization, Prev: Modules for Interfacing with the Operating System, Up: A Summary of the Various XEmacs Modules + +10.11 Modules for Interfacing with X Windows +============================================ + + Emacs.ad.h + + A file generated from `Emacs.ad', which contains XEmacs-supplied +fallback resources (so that XEmacs has pretty defaults). + + EmacsFrame.c + EmacsFrame.h + EmacsFrameP.h + + These modules implement an Xt widget class that encapsulates a frame. +This is for ease in integrating with Xt. The EmacsFrame widget covers +the entire X window except for the menubar; the scrollbars are +positioned on top of the EmacsFrame widget. + + *Warning:* Abandon hope, all ye who enter here. This code took an +ungodly amount of time to get right, and is likely to fall apart +mercilessly at the slightest change. Such is life under Xt. + + EmacsManager.c + EmacsManager.h + EmacsManagerP.h + + These modules implement a simple Xt manager (i.e. composite) widget +class that simply lets its children set whatever geometry they want. +It's amazing that Xt doesn't provide this standardly, but on second +thought, it makes sense, considering how amazingly broken Xt is. + + EmacsShell-sub.c + EmacsShell.c + EmacsShell.h + EmacsShellP.h + + These modules implement two Xt widget classes that are subclasses of +the TopLevelShell and TransientShell classes. This is necessary to deal +with more brokenness that Xt has sadistically thrust onto the backs of +developers. + + xgccache.c + xgccache.h + + These modules provide functions for maintenance and caching of GC's +(graphics contexts) under the X Window System. This code is junky and +needs to be rewritten. + + select-msw.c + select-x.c + select.c + select.h + + This module provides an interface to the X Window System's concept of +"selections", the standard way for X applications to communicate with +each other. + + xintrinsic.h + xintrinsicp.h + xmmanagerp.h + xmprimitivep.h + + These header files are similar in spirit to the `sys*.h' files and +buffer against different implementations of Xt and Motif. + + * `xintrinsic.h' should be included in place of `'. + + * `xintrinsicp.h' should be included in place of `'. + + * `xmmanagerp.h' should be included in place of `'. + + * `xmprimitivep.h' should be included in place of `'. + + xmu.c + xmu.h + + These files provide an emulation of the Xmu library for those systems +(i.e. HPUX) that don't provide it as a standard part of X. + + ExternalClient-Xlib.c + ExternalClient.c + ExternalClient.h + ExternalClientP.h + ExternalShell.c + ExternalShell.h + ExternalShellP.h + extw-Xlib.c + extw-Xlib.h + extw-Xt.c + extw-Xt.h + + These files provide the "external widget" interface, which allows an +XEmacs frame to appear as a widget in another application. To do this, +you have to configure with `--external-widget'. + + `ExternalShell*' provides the server (XEmacs) side of the connection. + + `ExternalClient*' provides the client (other application) side of +the connection. These files are not compiled into XEmacs but are +compiled into libraries that are then linked into your application. + + `extw-*' is common code that is used for both the client and server. + + Don't touch this code; something is liable to break if you do. + + +File: internals.info, Node: Modules for Internationalization, Next: Modules for Regression Testing, Prev: Modules for Interfacing with X Windows, Up: A Summary of the Various XEmacs Modules + +10.12 Modules for Internationalization +====================================== + + mule-canna.c + mule-ccl.c + mule-charset.c + mule-charset.h + file-coding.c + file-coding.h + mule-mcpath.c + mule-mcpath.h + mule-wnnfns.c + mule.c + + These files implement the MULE (Asian-language) support. Note that +MULE actually provides a general interface for all sorts of languages, +not just Asian languages (although they are generally the most +complicated to support). This code is still in beta. + + `mule-charset.*' and `file-coding.*' provide the heart of the XEmacs +MULE support. `mule-charset.*' implements the "charset" Lisp object +type, which encapsulates a character set (an ordered one- or +two-dimensional set of characters, such as US ASCII or JISX0208 Japanese +Kanji). + + `file-coding.*' implements the "coding-system" Lisp object type, +which encapsulates a method of converting between different encodings. +An encoding is a representation of a stream of characters, possibly +from multiple character sets, using a stream of bytes or words, and +defines (e.g.) which escape sequences are used to specify particular +character sets, how the indices for a character are converted into bytes +(sometimes this involves setting the high bit; sometimes complicated +rearranging of the values takes place, as in the Shift-JIS encoding), +etc. + + `mule-ccl.c' provides the CCL (Code Conversion Language) +interpreter. CCL is similar in spirit to Lisp byte code and is used to +implement converters for custom encodings. + + `mule-canna.c' and `mule-wnnfns.c' implement interfaces to external +programs used to implement the Canna and WNN input methods, +respectively. This is currently in beta. + + `mule-mcpath.c' provides some functions to allow for pathnames +containing extended characters. This code is fragmentary, obsolete, and +completely non-working. Instead, `pathname-coding-system' is used to +specify conversions of names of files and directories. The standard C +I/O functions like `open()' are wrapped so that conversion occurs +automatically. + + `mule.c' contains a few miscellaneous things. It currently seems to +be unused and probably should be removed. + + intl.c + + This provides some miscellaneous internationalization code for +implementing message translation and interfacing to the Ximp input +method. None of this code is currently working. + + iso-wide.h + + This contains leftover code from an earlier implementation of +Asian-language support, and is not currently used. + + +File: internals.info, Node: Modules for Regression Testing, Prev: Modules for Internationalization, Up: A Summary of the Various XEmacs Modules + +10.13 Modules for Regression Testing +==================================== + + test-harness.el + base64-tests.el + byte-compiler-tests.el + case-tests.el + ccl-tests.el + c-tests.el + database-tests.el + extent-tests.el + hash-table-tests.el + lisp-tests.el + md5-tests.el + mule-tests.el + regexp-tests.el + symbol-tests.el + syntax-tests.el + tag-tests.el + + `test-harness.el' defines the macros `Assert', `Check-Error', +`Check-Error-Message', and `Check-Message'. The other files are test +files, testing various XEmacs modules. + + +File: internals.info, Node: Allocation of Objects in XEmacs Lisp, Next: Dumping, Prev: A Summary of the Various XEmacs Modules, Up: Top + +11 Allocation of Objects in XEmacs Lisp +*************************************** + +* Menu: + +* Introduction to Allocation:: +* Garbage Collection:: +* GCPROing:: +* Garbage Collection - Step by Step:: +* Integers and Characters:: +* Allocation from Frob Blocks:: +* lrecords:: +* Low-level allocation:: +* Cons:: +* Vector:: +* Bit Vector:: +* Symbol:: +* Marker:: +* String:: +* Compiled Function:: + + +File: internals.info, Node: Introduction to Allocation, Next: Garbage Collection, Up: Allocation of Objects in XEmacs Lisp + +11.1 Introduction to Allocation +=============================== + +Emacs Lisp, like all Lisps, has garbage collection. This means that +the programmer never has to explicitly free (destroy) an object; it +happens automatically when the object becomes inaccessible. Most +experts agree that garbage collection is a necessity in a modern, +high-level language. Its omission from C stems from the fact that C was +originally designed to be a nice abstract layer on top of assembly +language, for writing kernels and basic system utilities rather than +large applications. + + Lisp objects can be created by any of a number of Lisp primitives. +Most object types have one or a small number of basic primitives for +creating objects. For conses, the basic primitive is `cons'; for +vectors, the primitives are `make-vector' and `vector'; for symbols, +the primitives are `make-symbol' and `intern'; etc. Some Lisp objects, +especially those that are primarily used internally, have no +corresponding Lisp primitives. Every Lisp object, though, has at least +one C primitive for creating it. + + Recall from section (VII) that a Lisp object, as stored in a 32-bit +or 64-bit word, has a few tag bits, and a "value" that occupies the +remainder of the bits. We can separate the different Lisp object types +into three broad categories: + + * (a) Those for whom the value directly represents the contents of + the Lisp object. Only two types are in this category: integers and + characters. No special allocation or garbage collection is + necessary for such objects. Lisp objects of these types do not + need to be `GCPRO'ed. + + In the remaining two categories, the type is stored in the object +itself. The tag for all such objects is the generic "lrecord" +(Lisp_Type_Record) tag. The first bytes of the object's structure are +an integer (actually a char) characterising the object's type and some +flags, in particular the mark bit used for garbage collection. A +structure describing the type is accessible thru the +lrecord_implementation_table indexed with said integer. This structure +includes the method pointers and a pointer to a string naming the type. + + * (b) Those lrecords that are allocated in frob blocks (see above). + This includes the objects that are most common and relatively + small, and includes conses, strings, subrs, floats, compiled + functions, symbols, extents, events, and markers. With the + cleanup of frob blocks done in 19.12, it's not terribly hard to + add more objects to this category, but it's a bit trickier than + adding an object type to type (c) (esp. if the object needs a + finalization method), and is not likely to save much space unless + the object is small and there are many of them. (In fact, if there + are very few of them, it might actually waste space.) + + * (c) Those lrecords that are individually `malloc()'ed. These are + called "lcrecords". All other types are in this category. Adding + a new type to this category is comparatively easy, and all types + added since 19.8 (when the current allocation scheme was devised, + by Richard Mlynarik), with the exception of the character type, + have been in this category. + + Note that bit vectors are a bit of a special case. They are simple +lrecords as in category (b), but are individually `malloc()'ed like +vectors. You can basically view them as exactly like vectors except +that their type is stored in lrecord fashion rather than in +directly-tagged fashion. + + +File: internals.info, Node: Garbage Collection, Next: GCPROing, Prev: Introduction to Allocation, Up: Allocation of Objects in XEmacs Lisp + +11.2 Garbage Collection +======================= + +Garbage collection is simple in theory but tricky to implement. Emacs +Lisp uses the oldest garbage collection method, called "mark and +sweep". Garbage collection begins by starting with all accessible +locations (i.e. all variables and other slots where Lisp objects might +occur) and recursively traversing all objects accessible from those +slots, marking each one that is found. We then go through all of +memory and free each object that is not marked, and unmarking each +object that is marked. Note that "all of memory" means all currently +allocated objects. Traversing all these objects means traversing all +frob blocks, all vectors (which are chained in one big list), and all +lcrecords (which are likewise chained). + + Garbage collection can be invoked explicitly by calling +`garbage-collect' but is also called automatically by `eval', once a +certain amount of memory has been allocated since the last garbage +collection (according to `gc-cons-threshold'). + + +File: internals.info, Node: GCPROing, Next: Garbage Collection - Step by Step, Prev: Garbage Collection, Up: Allocation of Objects in XEmacs Lisp + +11.3 `GCPRO'ing +=============== + +`GCPRO'ing is one of the ugliest and trickiest parts of Emacs +internals. The basic idea is that whenever garbage collection occurs, +all in-use objects must be reachable somehow or other from one of the +roots of accessibility. The roots of accessibility are: + + 1. All objects that have been `staticpro()'d or + `staticpro_nodump()'ed. This is used for any global C variables + that hold Lisp objects. A call to `staticpro()' happens implicitly + as a result of any symbols declared with `defsymbol()' and any + variables declared with `DEFVAR_FOO()'. You need to explicitly + call `staticpro()' (in the `vars_of_foo()' method of a module) for + other global C variables holding Lisp objects. (This typically + includes internal lists and such things.). Use + `staticpro_nodump()' only in the rare cases when you do not want + the pointed variable to be saved at dump time but rather recompute + it at startup. + + Note that `obarray' is one of the `staticpro()'d things. + Therefore, all functions and variables get marked through this. + + 2. Any shadowed bindings that are sitting on the `specpdl' stack. + + 3. Any objects sitting in currently active (Lisp) stack frames, + catches, and condition cases. + + 4. A couple of special-case places where active objects are located. + + 5. Anything currently marked with `GCPRO'. + + Marking with `GCPRO' is necessary because some C functions (quite a +lot, in fact), allocate objects during their operation. Quite +frequently, there will be no other pointer to the object while the +function is running, and if a garbage collection occurs and the object +needs to be referenced again, bad things will happen. The solution is +to mark those objects with `GCPRO'. Unfortunately this is easy to +forget, and there is basically no way around this problem. Here are +some rules, though: + + 1. For every `GCPRON', there have to be declarations of `struct gcpro + gcpro1, gcpro2', etc. + + 2. You _must_ `UNGCPRO' anything that's `GCPRO'ed, and you _must not_ + `UNGCPRO' if you haven't `GCPRO'ed. Getting either of these wrong + will lead to crashes, often in completely random places unrelated + to where the problem lies. + + 3. The way this actually works is that all currently active `GCPRO's + are chained through the `struct gcpro' local variables, with the + variable `gcprolist' pointing to the head of the list and the nth + local `gcpro' variable pointing to the first `gcpro' variable in + the next enclosing stack frame. Each `GCPRO'ed thing is an + lvalue, and the `struct gcpro' local variable contains a pointer to + this lvalue. This is why things will mess up badly if you don't + pair up the `GCPRO's and `UNGCPRO's--you will end up with + `gcprolist's containing pointers to `struct gcpro's or local + `Lisp_Object' variables in no-longer-active stack frames. + + 4. It is actually possible for a single `struct gcpro' to protect a + contiguous array of any number of values, rather than just a + single lvalue. To effect this, call `GCPRON' as usual on the + first object in the array and then set `gcproN.nvars'. + + 5. *Strings are relocated.* What this means in practice is that the + pointer obtained using `XSTRING_DATA()' is liable to change at any + time, and you should never keep it around past any function call, + or pass it as an argument to any function that might cause a + garbage collection. This is why a number of functions accept + either a "non-relocatable" `char *' pointer or a relocatable Lisp + string, and only access the Lisp string's data at the very last + minute. In some cases, you may end up having to `alloca()' some + space and copy the string's data into it. + + 6. By convention, if you have to nest `GCPRO''s, use `NGCPRON' (along + with `struct gcpro ngcpro1, ngcpro2', etc.), `NNGCPRON', etc. + This avoids compiler warnings about shadowed locals. + + 7. It is _always_ better to err on the side of extra `GCPRO's rather + than too few. The extra cycles spent on this are almost never + going to make a whit of difference in the speed of anything. + + 8. The general rule to follow is that caller, not callee, `GCPRO's. + That is, you should not have to explicitly `GCPRO' any Lisp objects + that are passed in as parameters. + + One exception from this rule is if you ever plan to change the + parameter value, and store a new object in it. In that case, you + _must_ `GCPRO' the parameter, because otherwise the new object + will not be protected. + + So, if you create any Lisp objects (remember, this happens in all + sorts of circumstances, e.g. with `Fcons()', etc.), you are + responsible for `GCPRO'ing them, unless you are _absolutely sure_ + that there's no possibility that a garbage-collection can occur + while you need to use the object. Even then, consider `GCPRO'ing. + + 9. A garbage collection can occur whenever anything calls `Feval', or + whenever a QUIT can occur where execution can continue past this. + (Remember, this is almost anywhere.) + + 10. If you have the _least smidgeon of doubt_ about whether you need + to `GCPRO', you should `GCPRO'. + + 11. Beware of `GCPRO'ing something that is uninitialized. If you have + any shade of doubt about this, initialize all your variables to + `Qnil'. + + 12. Be careful of traps, like calling `Fcons()' in the argument to + another function. By the "caller protects" law, you should be + `GCPRO'ing the newly-created cons, but you aren't. A certain + number of functions that are commonly called on freshly created + stuff (e.g. `nconc2()', `Fsignal()'), break the "caller protects" + law and go ahead and `GCPRO' their arguments so as to simplify + things, but make sure and check if it's OK whenever doing + something like this. + + 13. Once again, remember to `GCPRO'! Bugs resulting from insufficient + `GCPRO'ing are intermittent and extremely difficult to track down, + often showing up in crashes inside of `garbage-collect' or in + weirdly corrupted objects or even in incorrect values in a totally + different section of code. + + If you don't understand whether to `GCPRO' in a particular instance, +ask on the mailing lists. A general hint is that `prog1' is the +canonical example. + + Given the extremely error-prone nature of the `GCPRO' scheme, and +the difficulties in tracking down, it should be considered a deficiency +in the XEmacs code. A solution to this problem would involve +implementing so-called "conservative" garbage collection for the C +stack. That involves looking through all of stack memory and treating +anything that looks like a reference to an object as a reference. This +will result in a few objects not getting collected when they should, but +it obviates the need for `GCPRO'ing, and allows garbage collection to +happen at any point at all, such as during object allocation. + + +File: internals.info, Node: Garbage Collection - Step by Step, Next: Integers and Characters, Prev: GCPROing, Up: Allocation of Objects in XEmacs Lisp + +11.4 Garbage Collection - Step by Step +====================================== + +* Menu: + +* Invocation:: +* garbage_collect_1:: +* mark_object:: +* gc_sweep:: +* sweep_lcrecords_1:: +* compact_string_chars:: +* sweep_strings:: +* sweep_bit_vectors_1:: + + +File: internals.info, Node: Invocation, Next: garbage_collect_1, Up: Garbage Collection - Step by Step + +11.4.1 Invocation +----------------- + +The first thing that anyone should know about garbage collection is: +when and how the garbage collector is invoked. One might think that this +could happen every time new memory is allocated, e.g. new objects are +created, but this is _not_ the case. Instead, we have the following +situation: + + The entry point of any process of garbage collection is an invocation +of the function `garbage_collect_1' in file `alloc.c'. The invocation +can occur _explicitly_ by calling the function `Fgarbage_collect' (in +addition this function provides information about the freed memory), or +can occur _implicitly_ in four different situations: + 1. In function `main_1' in file `emacs.c'. This function is called at + each startup of xemacs. The garbage collection is invoked after all + initial creations are completed, but only if a special internal + error checking-constant `ERROR_CHECK_GC' is defined. + + 2. In function `disksave_object_finalization' in file `alloc.c'. The + only purpose of this function is to clear the objects from memory + which need not be stored with xemacs when we dump out an + executable. This is only done by `Fdump_emacs' or by + `Fdump_emacs_data' respectively (both in `emacs.c'). The actual + clearing is accomplished by making these objects unreachable and + starting a garbage collection. The function is only used while + building xemacs. + + 3. In function `Feval / eval' in file `eval.c'. Each time the well + known and often used function eval is called to evaluate a form, + one of the first things that could happen, is a potential call of + `garbage_collect_1'. There exist three global variables, + `consing_since_gc' (counts the created cons-cells since the last + garbage collection), `gc_cons_threshold' (a specified threshold + after which a garbage collection occurs) and `always_gc'. If + `always_gc' is set or if the threshold is exceeded, the garbage + collection will start. + + 4. In function `Ffuncall / funcall' in file `eval.c'. This function + evaluates calls of elisp functions and works according to `Feval'. + + The upshot is that garbage collection can basically occur everywhere +`Feval', respectively `Ffuncall', is used - either directly or through +another function. Since calls to these two functions are hidden in +various other functions, many calls to `garbage_collect_1' are not +obviously foreseeable, and therefore unexpected. Instances where they +are used that are worth remembering are various elisp commands, as for +example `or', `and', `if', `cond', `while', `setq', etc., miscellaneous +`gui_item_...' functions, everything related to `eval' (`Feval_buffer', +`call0', ...) and inside `Fsignal'. The latter is used to handle +signals, as for example the ones raised by every `QUIT'-macro triggered +after pressing Ctrl-g. + + +File: internals.info, Node: garbage_collect_1, Next: mark_object, Prev: Invocation, Up: Garbage Collection - Step by Step + +11.4.2 `garbage_collect_1' +-------------------------- + +We can now describe exactly what happens after the invocation takes +place. + 1. There are several cases in which the garbage collector is left + immediately: when we are already garbage collecting + (`gc_in_progress'), when the garbage collection is somehow + forbidden (`gc_currently_forbidden'), when we are currently + displaying something (`in_display') or when we are preparing for + the armageddon of the whole system (`preparing_for_armageddon'). + + 2. Next the correct frame in which to put all the output occurring + during garbage collecting is determined. In order to be able to + restore the old display's state after displaying the message, some + data about the current cursor position has to be saved. The + variables `pre_gc_cursor' and `cursor_changed' take care of that. + + 3. The state of `gc_currently_forbidden' must be restored after the + garbage collection, no matter what happens during the process. We + accomplish this by `record_unwind_protect'ing the suitable function + `restore_gc_inhibit' together with the current value of + `gc_currently_forbidden'. + + 4. If we are concurrently running an interactive xemacs session, the + next step is simply to show the garbage collector's cursor/message. + + 5. The following steps are the intrinsic steps of the garbage + collector, therefore `gc_in_progress' is set. + + 6. For debugging purposes, it is possible to copy the current C stack + frame. However, this seems to be a currently unused feature. + + 7. Before actually starting to go over all live objects, references to + objects that are no longer used are pruned. We only have to do + this for events (`clear_event_resource') and for specifiers + (`cleanup_specifiers'). + + 8. Now the mark phase begins and marks all accessible elements. In + order to start from all slots that serve as roots of + accessibility, the function `mark_object' is called for each root + individually to go out from there to mark all reachable objects. + All roots that are traversed are shown in their processed order: + * all constant symbols and static variables that are registered + via `staticpro' in the dynarr `staticpros'. *Note Adding + Global Lisp Variables::. + + * all Lisp objects that are created in C functions and that + must be protected from freeing them. They are registered in + the global list `gcprolist'. *Note GCPROing::. + + * all local variables (i.e. their name fields `symbol' and old + values `old_values') that are bound during the evaluation by + the Lisp engine. They are stored in `specbinding' structs + pushed on a stack called `specpdl'. *Note Dynamic Binding; + The specbinding Stack; Unwind-Protects::. + + * all catch blocks that the Lisp engine encounters during the + evaluation cause the creation of structs `catchtag' inserted + in the list `catchlist'. Their tag (`tag') and value (`val' + fields are freshly created objects and therefore have to be + marked. *Note Catch and Throw::. + + * every function application pushes new structs `backtrace' on + the call stack of the Lisp engine (`backtrace_list'). The + unique parts that have to be marked are the fields for each + function (`function') and all their arguments (`args'). + *Note Evaluation::. + + * all objects that are used by the redisplay engine that must + not be freed are marked by a special function called + `mark_redisplay' (in `redisplay.c'). + + * all objects created for profiling purposes are allocated by C + functions instead of using the lisp allocation mechanisms. In + order to receive the right ones during the sweep phase, they + also have to be marked manually. That is done by the function + `mark_profiling_info' + + 9. Hash tables in XEmacs belong to a kind of special objects that + make use of a concept often called 'weak pointers'. To make a + long story short, these kind of pointers are not followed during + the estimation of the live objects during garbage collection. Any + object referenced only by weak pointers is collected anyway, and + the reference to it is cleared. In hash tables there are different + usage patterns of them, manifesting in different types of hash + tables, namely 'non-weak', 'weak', 'key-weak' and 'value-weak' + (internally also 'key-car-weak' and 'value-car-weak') hash tables, + each clearing entries depending on different conditions. More + information can be found in the documentation to the function + `make-hash-table'. + + Because there are complicated dependency rules about when and what + to mark while processing weak hash tables, the standard `marker' + method is only active if it is marking non-weak hash tables. As + soon as a weak component is in the table, the hash table entries + are ignored while marking. Instead their marking is done each + separately by the function `finish_marking_weak_hash_tables'. This + function iterates over each hash table entry `hentries' for each + weak hash table in `Vall_weak_hash_tables'. Depending on the type + of a table, the appropriate action is performed. If a table is + acting as `HASH_TABLE_KEY_WEAK', and a key already marked, + everything reachable from the `value' component is marked. If it is + acting as a `HASH_TABLE_VALUE_WEAK' and the value component is + already marked, the marking starts beginning only from the `key' + component. If it is a `HASH_TABLE_KEY_CAR_WEAK' and the car of + the key entry is already marked, we mark both the `key' and + `value' components. Finally, if the table is of the type + `HASH_TABLE_VALUE_CAR_WEAK' and the car of the value components is + already marked, again both the `key' and the `value' components + get marked. + + Again, there are lists with comparable properties called weak + lists. There exist different peculiarities of their types called + `simple', `assoc', `key-assoc' and `value-assoc'. You can find + further details about them in the description to the function + `make-weak-list'. The scheme of their marking is similar: all weak + lists are listed in `Qall_weak_lists', therefore we iterate over + them. The marking is advanced until we hit an already marked pair. + Then we know that during a former run all the rest has been marked + completely. Again, depending on the special type of the weak list, + our jobs differ. If it is a `WEAK_LIST_SIMPLE' and the elem is + marked, we mark the `cons' part. If it is a `WEAK_LIST_ASSOC' and + not a pair or a pair with both marked car and cdr, we mark the + `cons' and the `elem'. If it is a `WEAK_LIST_KEY_ASSOC' and not a + pair or a pair with a marked car of the elem, we mark the `cons' + and the `elem'. Finally, if it is a `WEAK_LIST_VALUE_ASSOC' and + not a pair or a pair with a marked cdr of the elem, we mark both + the `cons' and the `elem'. + + Since, by marking objects in reach from weak hash tables and weak + lists, other objects could get marked, this perhaps implies + further marking of other weak objects, both finishing functions + are redone as long as yet unmarked objects get freshly marked. + + 10. After completing the special marking for the weak hash tables and + for the weak lists, all entries that point to objects that are + going to be swept in the further process are useless, and + therefore have to be removed from the table or the list. + + The function `prune_weak_hash_tables' does the job for weak hash + tables. Totally unmarked hash tables are removed from the list + `Vall_weak_hash_tables'. The other ones are treated more carefully + by scanning over all entries and removing one as soon as one of + the components `key' and `value' is unmarked. + + The same idea applies to the weak lists. It is accomplished by + `prune_weak_lists': An unmarked list is pruned from + `Vall_weak_lists' immediately. A marked list is treated more + carefully by going over it and removing just the unmarked pairs. + + 11. The function `prune_specifiers' checks all listed specifiers held + in `Vall_specifiers' and removes the ones from the lists that are + unmarked. + + 12. All syntax tables are stored in a list called + `Vall_syntax_tables'. The function `prune_syntax_tables' walks + through it and unlinks the tables that are unmarked. + + 13. Next, we will attack the complete sweeping - the function + `gc_sweep' which holds the predominance. + + 14. First, all the variables with respect to garbage collection are + reset. `consing_since_gc' - the counter of the created cells since + the last garbage collection - is set back to 0, and + `gc_in_progress' is not `true' anymore. + + 15. In case the session is interactive, the displayed cursor and + message are removed again. + + 16. The state of `gc_inhibit' is restored to the former value by + unwinding the stack. + + 17. A small memory reserve is always held back that can be reached by + `breathing_space'. If nothing more is left, we create a new reserve + and exit. + + +File: internals.info, Node: mark_object, Next: gc_sweep, Prev: garbage_collect_1, Up: Garbage Collection - Step by Step + +11.4.3 `mark_object' +-------------------- + +The first thing that is checked while marking an object is whether the +object is a real Lisp object `Lisp_Type_Record' or just an integer or a +character. Integers and characters are the only two types that are +stored directly - without another level of indirection, and therefore +they don't have to be marked and collected. *Note How Lisp Objects Are +Represented in C::. + + The second case is the one we have to handle. It is the one when we +are dealing with a pointer to a Lisp object. But, there exist also three +possibilities, that prevent us from doing anything while marking: The +object is read only which prevents it from being garbage collected, +i.e. marked (`C_READONLY_RECORD_HEADER'). The object in question is +already marked, and need not be marked for the second time (checked by +`MARKED_RECORD_HEADER_P'). If it is a special, unmarkable object +(`UNMARKABLE_RECORD_HEADER_P', apparently, these are objects that sit +in some const space, and can therefore not be marked, see +`this_one_is_unmarkable' in `alloc.c'). + + Now, the actual marking is feasible. We do so by once using the macro +`MARK_RECORD_HEADER' to mark the object itself (actually the special +flag in the lrecord header), and calling its special marker "method" +`marker' if available. The marker method marks every other object that +is in reach from our current object. Note, that these marker methods +should not call `mark_object' recursively, but instead should return +the next object from where further marking has to be performed. + + In case another object was returned, as mentioned before, we +reiterate the whole `mark_object' process beginning with this next +object. + + +File: internals.info, Node: gc_sweep, Next: sweep_lcrecords_1, Prev: mark_object, Up: Garbage Collection - Step by Step + +11.4.4 `gc_sweep' +----------------- + +The job of this function is to free all unmarked records from memory. As +we know, there are different types of objects implemented and managed, +and consequently different ways to free them from memory. *Note +Introduction to Allocation::. + + We start with all objects stored through `lcrecords'. All bulkier +objects are allocated and handled using that scheme of `lcrecords'. +Each object is `malloc'ed separately instead of placing it in one of +the contiguous frob blocks. All types that are currently stored using +`lcrecords''s `alloc_lcrecord' and `make_lcrecord_list' are the types: +vectors, buffers, char-table, char-table-entry, console, weak-list, +database, device, ldap, hash-table, command-builder, extent-auxiliary, +extent-info, face, coding-system, frame, image-instance, glyph, +popup-data, gui-item, keymap, charset, color_instance, font_instance, +opaque, opaque-list, process, range-table, specifier, +symbol-value-buffer-local, symbol-value-lisp-magic, +symbol-value-varalias, toolbar-button, tooltalk-message, +tooltalk-pattern, window, and window-configuration. We take care of +them in the fist place in order to be able to handle and to finalize +items stored in them more easily. The function `sweep_lcrecords_1' as +described below is doing the whole job for us. For a description about +the internals: *Note lrecords::. + + Our next candidates are the other objects that behave quite +differently than everything else: the strings. They consists of two +parts, a fixed-size portion (`struct Lisp_String') holding the string's +length, its property list and a pointer to the second part, and the +actual string data, which is stored in string-chars blocks comparable to +frob blocks. In this block, the data is not only freed, but also a +compression of holes is made, i.e. all strings are relocated together. +*Note String::. This compacting phase is performed by the function +`compact_string_chars', the actual sweeping by the function +`sweep_strings' is described below. + + After that, the other types are swept step by step using functions +`sweep_conses', `sweep_bit_vectors_1', `sweep_compiled_functions', +`sweep_floats', `sweep_symbols', `sweep_extents', `sweep_markers' and +`sweep_extents'. They are the fixed-size types cons, floats, +compiled-functions, symbol, marker, extent, and event stored in +so-called "frob blocks", and therefore we can basically do the same on +every type objects, using the same macros, especially defined only to +handle everything with respect to fixed-size blocks. The only fixed-size +type that is not handled here are the fixed-size portion of strings, +because we took special care of them earlier. + + The only big exceptions are bit vectors stored differently and +therefore treated differently by the function `sweep_bit_vectors_1' +described later. + + At first, we need some brief information about how these fixed-size +types are managed in general, in order to understand how the sweeping +is done. They have all a fixed size, and are therefore stored in big +blocks of memory - allocated at once - that can hold a certain amount +of objects of one type. The macro `DECLARE_FIXED_TYPE_ALLOC' creates +the suitable structures for every type. More precisely, we have the +block struct (holding a pointer to the previous block `prev' and the +objects in `block[]'), a pointer to current block +(`current_..._block)') and its last index (`current_..._block_index'), +and a pointer to the free list that will be created. Also a macro +`FIXED_TYPE_FROM_BLOCK' plus some related macros exists that are used +to obtain a new object, either from the free list +`ALLOCATE_FIXED_TYPE_1' if there is an unused object of that type +stored or by allocating a completely new block using +`ALLOCATE_FIXED_TYPE_FROM_BLOCK'. + + The rest works as follows: all of them define a macro `UNMARK_...' +that is used to unmark the object. They define a macro +`ADDITIONAL_FREE_...' that defines additional work that has to be done +when converting an object from in use to not in use (so far, only +markers use it in order to unchain them). Then, they all call the macro +`SWEEP_FIXED_TYPE_BLOCK' instantiated with their type name and their +struct name. + + This call in particular does the following: we go over all blocks +starting with the current moving towards the oldest. For each block, +we look at every object in it. If the object already freed (checked +with `FREE_STRUCT_P' using the first pointer of the object), or if it is +set to read only (`C_READONLY_RECORD_HEADER_P', nothing must be done. +If it is unmarked (checked with `MARKED_RECORD_HEADER_P'), it is put in +the free list and set free (using the macro `FREE_FIXED_TYPE', +otherwise it stays in the block, but is unmarked (by `UNMARK_...'). +While going through one block, we note if the whole block is empty. If +so, the whole block is freed (using `xfree') and the free list state is +set to the state it had before handling this block. + + +File: internals.info, Node: sweep_lcrecords_1, Next: compact_string_chars, Prev: gc_sweep, Up: Garbage Collection - Step by Step + +11.4.5 `sweep_lcrecords_1' +-------------------------- + +After nullifying the complete lcrecord statistics, we go over all +lcrecords two separate times. They are all chained together in a list +with a head called `all_lcrecords'. + + The first loop calls for each object its `finalizer' method, but only +in the case that it is not read only (`C_READONLY_RECORD_HEADER_P)', it +is not already marked (`MARKED_RECORD_HEADER_P'), it is not already in +a free list (list of freed objects, field `free') and finally it owns a +finalizer method. + + The second loop actually frees the appropriate objects again by +iterating through the whole list. In case an object is read only or +marked, it has to persist, otherwise it is manually freed by calling +`xfree'. During this loop, the lcrecord statistics are kept up to date +by calling `tick_lcrecord_stats' with the right arguments, + + +File: internals.info, Node: compact_string_chars, Next: sweep_strings, Prev: sweep_lcrecords_1, Up: Garbage Collection - Step by Step + +11.4.6 `compact_string_chars' +----------------------------- + +The purpose of this function is to compact all the data parts of the +strings that are held in so-called `string_chars_block', i.e. the +strings that do not exceed a certain maximal length. + + The procedure with which this is done is as follows. We are keeping +two positions in the `string_chars_block's using two pointer/integer +pairs, namely `from_sb'/`from_pos' and `to_sb'/`to_pos'. They stand for +the actual positions, from where to where, to copy the actually handled +string. + + While going over all chained `string_char_block's and their held +strings, staring at `first_string_chars_block', both pointers are +advanced and eventually a string is copied from `from_sb' to `to_sb', +depending on the status of the pointed at strings. + + More precisely, we can distinguish between the following actions. + * The string at `from_sb''s position could be marked as free, which + is indicated by an invalid pointer to the pointer that should + point back to the fixed size string object, and which is checked by + `FREE_STRUCT_P'. In this case, the `from_sb'/`from_pos' is + advanced to the next string, and nothing has to be copied. + + * Also, if a string object itself is unmarked, nothing has to be + copied. We likewise advance the `from_sb'/`from_pos' pair as + described above. + + * In all other cases, we have a marked string at hand. The string + data must be moved from the from-position to the to-position. In + case there is not enough space in the actual `to_sb'-block, we + advance this pointer to the beginning of the next block before + copying. In case the from and to positions are different, we + perform the actual copying using the library function `memmove'. + + After compacting, the pointer to the current `string_chars_block', +sitting in `current_string_chars_block', is reset on the last block to +which we moved a string, i.e. `to_block', and all remaining blocks (we +know that they just carry garbage) are explicitly `xfree'd. + + +File: internals.info, Node: sweep_strings, Next: sweep_bit_vectors_1, Prev: compact_string_chars, Up: Garbage Collection - Step by Step + +11.4.7 `sweep_strings' +---------------------- + +The sweeping for the fixed sized string objects is essentially exactly +the same as it is for all other fixed size types. As before, the freeing +into the suitable free list is done by using the macro +`SWEEP_FIXED_SIZE_BLOCK' after defining the right macros +`UNMARK_string' and `ADDITIONAL_FREE_string'. These two definitions are +a little bit special compared to the ones used for the other fixed size +types. + + `UNMARK_string' is defined the same way except some additional code +used for updating the bookkeeping information. + + For strings, `ADDITIONAL_FREE_string' has to do something in +addition: in case, the string was not allocated in a +`string_chars_block' because it exceeded the maximal length, and +therefore it was `malloc'ed separately, we know also `xfree' it +explicitly. + + +File: internals.info, Node: sweep_bit_vectors_1, Prev: sweep_strings, Up: Garbage Collection - Step by Step + +11.4.8 `sweep_bit_vectors_1' +---------------------------- + +Bit vectors are also one of the rare types that are `malloc'ed +individually. Consequently, while sweeping, all further needless bit +vectors must be freed by hand. This is done, as one might imagine, the +expected way: since they are all registered in a list called +`all_bit_vectors', all elements of that list are traversed, all +unmarked bit vectors are unlinked by calling `xfree' and all of them +become unmarked. In addition, the bookkeeping information used for +garbage collector's output purposes is updated. + + +File: internals.info, Node: Integers and Characters, Next: Allocation from Frob Blocks, Prev: Garbage Collection - Step by Step, Up: Allocation of Objects in XEmacs Lisp + +11.5 Integers and Characters +============================ + +Integer and character Lisp objects are created from integers using the +macros `XSETINT()' and `XSETCHAR()' or the equivalent functions +`make_int()' and `make_char()'. (These are actually macros on most +systems.) These functions basically just do some moving of bits +around, since the integral value of the object is stored directly in +the `Lisp_Object'. + + `XSETINT()' and the like will truncate values given to them that are +too big; i.e. you won't get the value you expected but the tag bits +will at least be correct. + + +File: internals.info, Node: Allocation from Frob Blocks, Next: lrecords, Prev: Integers and Characters, Up: Allocation of Objects in XEmacs Lisp + +11.6 Allocation from Frob Blocks +================================ + +The uninitialized memory required by a `Lisp_Object' of a particular +type is allocated using `ALLOCATE_FIXED_TYPE()'. This only occurs +inside of the lowest-level object-creating functions in `alloc.c': +`Fcons()', `make_float()', `Fmake_byte_code()', `Fmake_symbol()', +`allocate_extent()', `allocate_event()', `Fmake_marker()', and +`make_uninit_string()'. The idea is that, for each type, there are a +number of frob blocks (each 2K in size); each frob block is divided up +into object-sized chunks. Each frob block will have some of these +chunks that are currently assigned to objects, and perhaps some that are +free. (If a frob block has nothing but free chunks, it is freed at the +end of the garbage collection cycle.) The free chunks are stored in a +free list, which is chained by storing a pointer in the first four bytes +of the chunk. (Except for the free chunks at the end of the last frob +block, which are handled using an index which points past the end of the +last-allocated chunk in the last frob block.) `ALLOCATE_FIXED_TYPE()' +first tries to retrieve a chunk from the free list; if that fails, it +calls `ALLOCATE_FIXED_TYPE_FROM_BLOCK()', which looks at the end of the +last frob block for space, and creates a new frob block if there is +none. (There are actually two versions of these macros, one of which is +more defensive but less efficient and is used for error-checking.) + + +File: internals.info, Node: lrecords, Next: Low-level allocation, Prev: Allocation from Frob Blocks, Up: Allocation of Objects in XEmacs Lisp + +11.7 lrecords +============= + +[see `lrecord.h'] + + All lrecords have at the beginning of their structure a `struct +lrecord_header'. This just contains a type number and some flags, +including the mark bit. All builtin type numbers are defined as +constants in `enum lrecord_type', to allow the compiler to generate +more efficient code for `TYPEP'. The type number, thru the +`lrecord_implementation_table', gives access to a `struct +lrecord_implementation', which is a structure containing method pointers +and such. There is one of these for each type, and it is a global, +constant, statically-declared structure that is declared in the +`DEFINE_LRECORD_IMPLEMENTATION()' macro. + + Simple lrecords (of type (b) above) just have a `struct +lrecord_header' at their beginning. lcrecords, however, actually have a +`struct lcrecord_header'. This, in turn, has a `struct lrecord_header' +at its beginning, so sanity is preserved; but it also has a pointer +used to chain all lcrecords together, and a special ID field used to +distinguish one lcrecord from another. (This field is used only for +debugging and could be removed, but the space gain is not significant.) + + Simple lrecords are created using `ALLOCATE_FIXED_TYPE()', just like +for other frob blocks. The only change is that the implementation +pointer must be initialized correctly. (The implementation structure for +an lrecord, or rather the pointer to it, is named `lrecord_float', +`lrecord_extent', `lrecord_buffer', etc.) + + lcrecords are created using `alloc_lcrecord()'. This takes a size +to allocate and an implementation pointer. (The size needs to be passed +because some lcrecords, such as window configurations, are of variable +size.) This basically just `malloc()'s the storage, initializes the +`struct lcrecord_header', and chains the lcrecord onto the head of the +list of all lcrecords, which is stored in the variable `all_lcrecords'. +The calls to `alloc_lcrecord()' generally occur in the lowest-level +allocation function for each lrecord type. + + Whenever you create an lrecord, you need to call either +`DEFINE_LRECORD_IMPLEMENTATION()' or +`DEFINE_LRECORD_SEQUENCE_IMPLEMENTATION()'. This needs to be specified +in a `.c' file, at the top level. What this actually does is define +and initialize the implementation structure for the lrecord. (And +possibly declares a function `error_check_foo()' that implements the +`XFOO()' macro when error-checking is enabled.) The arguments to the +macros are the actual type name (this is used to construct the C +variable name of the lrecord implementation structure and related +structures using the `##' macro concatenation operator), a string that +names the type on the Lisp level (this may not be the same as the C +type name; typically, the C type name has underscores, while the Lisp +string has dashes), various method pointers, and the name of the C +structure that contains the object. The methods are used to +encapsulate type-specific information about the object, such as how to +print it or mark it for garbage collection, so that it's easy to add +new object types without having to add a specific case for each new +type in a bunch of different places. + + The difference between `DEFINE_LRECORD_IMPLEMENTATION()' and +`DEFINE_LRECORD_SEQUENCE_IMPLEMENTATION()' is that the former is used +for fixed-size object types and the latter is for variable-size object +types. Most object types are fixed-size; some complex types, however +(e.g. window configurations), are variable-size. Variable-size object +types have an extra method, which is called to determine the actual +size of a particular object of that type. (Currently this is only used +for keeping allocation statistics.) + + For the purpose of keeping allocation statistics, the allocation +engine keeps a list of all the different types that exist. Note that, +since `DEFINE_LRECORD_IMPLEMENTATION()' is a macro that is specified at +top-level, there is no way for it to initialize the global data +structures containing type information, like +`lrecord_implementations_table'. For this reason a call to +`INIT_LRECORD_IMPLEMENTATION' must be added to the same source file +containing `DEFINE_LRECORD_IMPLEMENTATION', but instead of to the top +level, to one of the init functions, typically `syms_of_FOO.c'. +`INIT_LRECORD_IMPLEMENTATION' must be called before an object of this +type is used. + + The type number is also used to index into an array holding the +number of objects of each type and the total memory allocated for +objects of that type. The statistics in this array are computed during +the sweep stage. These statistics are returned by the call to +`garbage-collect'. + + Note that for every type defined with a `DEFINE_LRECORD_*()' macro, +there needs to be a `DECLARE_LRECORD_IMPLEMENTATION()' somewhere in a +`.h' file, and this `.h' file needs to be included by `inline.c'. + + Furthermore, there should generally be a set of `XFOOBAR()', +`FOOBARP()', etc. macros in a `.h' (or occasionally `.c') file. To +create one of these, copy an existing model and modify as necessary. + + *Please note:* If you define an lrecord in an external +dynamically-loaded module, you must use `DECLARE_EXTERNAL_LRECORD', +`DEFINE_EXTERNAL_LRECORD_IMPLEMENTATION', and +`DEFINE_EXTERNAL_LRECORD_SEQUENCE_IMPLEMENTATION' instead of the +non-EXTERNAL forms. These macros will dynamically add new type numbers +to the global enum that records them, whereas the non-EXTERNAL forms +assume that the programmer has already inserted the correct type numbers +into the enum's code at compile-time. + + The various methods in the lrecord implementation structure are: + + 1. A "mark" method. This is called during the marking stage and + passed a function pointer (usually the `mark_object()' function), + which is used to mark an object. All Lisp objects that are + contained within the object need to be marked by applying this + function to them. The mark method should also return a Lisp + object, which should be either `nil' or an object to mark. (This + can be used in lieu of calling `mark_object()' on the object, to + reduce the recursion depth, and consequently should be the most + heavily nested sub-object, such as a long list.) + + *Please note:* When the mark method is called, garbage collection + is in progress, and special precautions need to be taken when + accessing objects; see section (B) above. + + If your mark method does not need to do anything, it can be `NULL'. + + 2. A "print" method. This is called to create a printed + representation of the object, whenever `princ', `prin1', or the + like is called. It is passed the object, a stream to which the + output is to be directed, and an `escapeflag' which indicates + whether the object's printed representation should be "escaped" so + that it is readable. (This corresponds to the difference between + `princ' and `prin1'.) Basically, "escaped" means that strings will + have quotes around them and confusing characters in the strings + such as quotes, backslashes, and newlines will be backslashed; and + that special care will be taken to make symbols print in a + readable fashion (e.g. symbols that look like numbers will be + backslashed). Other readable objects should perhaps pass + `escapeflag' on when sub-objects are printed, so that readability + is preserved when necessary (or if not, always pass in a 1 for + `escapeflag'). Non-readable objects should in general ignore + `escapeflag', except that some use it as an indication that more + verbose output should be given. + + Sub-objects are printed using `print_internal()', which takes + exactly the same arguments as are passed to the print method. + + Literal C strings should be printed using `write_c_string()', or + `write_string_1()' for non-null-terminated strings. + + Functions that do not have a readable representation should check + the `print_readably' flag and signal an error if it is set. + + If you specify NULL for the print method, the + `default_object_printer()' will be used. + + 3. A "finalize" method. This is called at the beginning of the sweep + stage on lcrecords that are about to be freed, and should be used + to perform any extra object cleanup. This typically involves + freeing any extra `malloc()'ed memory associated with the object, + releasing any operating-system and window-system resources + associated with the object (e.g. pixmaps, fonts), etc. + + The finalize method can be NULL if nothing needs to be done. + + WARNING #1: The finalize method is also called at the end of the + dump phase; this time with the for_disksave parameter set to + non-zero. The object is _not_ about to disappear, so you have to + make sure to _not_ free any extra `malloc()'ed memory if you're + going to need it later. (Also, signal an error if there are any + operating-system and window-system resources here, because they + can't be dumped.) + + Finalize methods should, as a rule, set to zero any pointers after + they've been freed, and check to make sure pointers are not zero + before freeing. Although I'm pretty sure that finalize methods + are not called twice on the same object (except for the + `for_disksave' proviso), we've gotten nastily burned in some cases + by not doing this. + + WARNING #2: The finalize method is _only_ called for lcrecords, + _not_ for simply lrecords. If you need a finalize method for + simple lrecords, you have to stick it in the + `ADDITIONAL_FREE_foo()' macro in `alloc.c'. + + WARNING #3: Things are in an _extremely_ bizarre state when + `ADDITIONAL_FREE_foo()' is called, so you have to be incredibly + careful when writing one of these functions. See the comment in + `gc_sweep()'. If you ever have to add one of these, consider + using an lcrecord or dealing with the problem in a different + fashion. + + 4. An "equal" method. This compares the two objects for similarity, + when `equal' is called. It should compare the contents of the + objects in some reasonable fashion. It is passed the two objects + and a "depth" value, which is used to catch circular objects. To + compare sub-Lisp-objects, call `internal_equal()' and bump the + depth value by one. If this value gets too high, a + `circular-object' error will be signaled. + + If this is NULL, objects are `equal' only when they are `eq', i.e. + identical. + + 5. A "hash" method. This is used to hash objects when they are to be + compared with `equal'. The rule here is that if two objects are + `equal', they _must_ hash to the same value; i.e. your hash + function should use some subset of the sub-fields of the object + that are compared in the "equal" method. If you specify this + method as `NULL', the object's pointer will be used as the hash, + which will _fail_ if the object has an `equal' method, so don't do + this. + + To hash a sub-Lisp-object, call `internal_hash()'. Bump the depth + by one, just like in the "equal" method. + + To convert a Lisp object directly into a hash value (using its + pointer), use `LISP_HASH()'. This is what happens when the hash + method is NULL. + + To hash two or more values together into a single value, use + `HASH2()', `HASH3()', `HASH4()', etc. + + 6. "getprop", "putprop", "remprop", and "plist" methods. These are + used for object types that have properties. I don't feel like + documenting them here. If you create one of these objects, you + have to use different macros to define them, i.e. + `DEFINE_LRECORD_IMPLEMENTATION_WITH_PROPS()' or + `DEFINE_LRECORD_SEQUENCE_IMPLEMENTATION_WITH_PROPS()'. + + 7. A "size_in_bytes" method, when the object is of variable-size. + (i.e. declared with a `_SEQUENCE_IMPLEMENTATION' macro.) This + should simply return the object's size in bytes, exactly as you + might expect. For an example, see the methods for window + configurations and opaques. + + +File: internals.info, Node: Low-level allocation, Next: Cons, Prev: lrecords, Up: Allocation of Objects in XEmacs Lisp + +11.8 Low-level allocation +========================= + +Memory that you want to allocate directly should be allocated using +`xmalloc()' rather than `malloc()'. This implements error-checking on +the return value, and once upon a time did some more vital stuff (i.e. +`BLOCK_INPUT', which is no longer necessary). Free using `xfree()', +and realloc using `xrealloc()'. Note that `xmalloc()' will do a +non-local exit if the memory can't be allocated. (Many functions, +however, do not expect this, and thus XEmacs will likely crash if this +happens. *This is a bug.* If you can, you should strive to make your +function handle this OK. However, it's difficult in the general +circumstance, perhaps requiring extra unwind-protects and such.) + + Note that XEmacs provides two separate replacements for the standard +`malloc()' library function. These are called "old GNU malloc" +(`malloc.c') and "new GNU malloc" (`gmalloc.c'), respectively. New GNU +malloc is better in pretty much every way than old GNU malloc, and +should be used if possible. (It used to be that on some systems, the +old one worked but the new one didn't. I think this was due +specifically to a bug in SunOS, which the new one now works around; so +I don't think the old one ever has to be used any more.) The primary +difference between both of these mallocs and the standard system malloc +is that they are much faster, at the expense of increased space. The +basic idea is that memory is allocated in fixed chunks of powers of +two. This allows for basically constant malloc time, since the various +chunks can just be kept on a number of free lists. (The standard system +malloc typically allocates arbitrary-sized chunks and has to spend some +time, sometimes a significant amount of time, walking the heap looking +for a free block to use and cleaning things up.) The new GNU malloc +improves on things by allocating large objects in chunks of 4096 bytes +rather than in ever larger powers of two, which results in ever larger +wastage. There is a slight speed loss here, but it's of doubtful +significance. + + NOTE: Apparently there is a third-generation GNU malloc that is +significantly better than the new GNU malloc, and should probably be +included in XEmacs. + + There is also the relocating allocator, `ralloc.c'. This actually +moves blocks of memory around so that the `sbrk()' pointer shrunk and +virtual memory released back to the system. On some systems, this is a +big win. On all systems, it causes a noticeable (and sometimes huge) +speed penalty, so I turn it off by default. `ralloc.c' only works with +the new GNU malloc in `gmalloc.c'. There are also two versions of +`ralloc.c', one that uses `mmap()' rather than block copies to move +data around. This purports to be faster, although that depends on the +amount of data that would have had to be block copied and the +system-call overhead for `mmap()'. I don't know exactly how this +works, except that the relocating-allocation routines are pretty much +used only for the memory allocated for a buffer, which is the biggest +consumer of space, esp. of space that may get freed later. + + Note that the GNU mallocs have some "memory warning" facilities. +XEmacs taps into them and issues a warning through the standard warning +system, when memory gets to 75%, 85%, and 95% full. (On some systems, +the memory warnings are not functional.) + + Allocated memory that is going to be used to make a Lisp object is +created using `allocate_lisp_storage()'. This just calls `xmalloc()'. +It used to verify that the pointer to the memory can fit into a Lisp +word, before the current Lisp object representation was introduced. +`allocate_lisp_storage()' is called by `alloc_lcrecord()', +`ALLOCATE_FIXED_TYPE()', and the vector and bit-vector creation +routines. These routines also call `INCREMENT_CONS_COUNTER()' at the +appropriate times; this keeps statistics on how much memory is +allocated, so that garbage-collection can be invoked when the threshold +is reached. + + +File: internals.info, Node: Cons, Next: Vector, Prev: Low-level allocation, Up: Allocation of Objects in XEmacs Lisp + +11.9 Cons +========= + +Conses are allocated in standard frob blocks. The only thing to note +is that conses can be explicitly freed using `free_cons()' and +associated functions `free_list()' and `free_alist()'. This +immediately puts the conses onto the cons free list, and decrements the +statistics on memory allocation appropriately. This is used to good +effect by some extremely commonly-used code, to avoid generating extra +objects and thereby triggering GC sooner. However, you have to be +_extremely_ careful when doing this. If you mess this up, you will get +BADLY BURNED, and it has happened before. + + +File: internals.info, Node: Vector, Next: Bit Vector, Prev: Cons, Up: Allocation of Objects in XEmacs Lisp + +11.10 Vector +============ + +As mentioned above, each vector is `malloc()'ed individually, and all +are threaded through the variable `all_vectors'. Vectors are marked +strangely during garbage collection, by kludging the size field. Note +that the `struct Lisp_Vector' is declared with its `contents' field +being a _stretchy_ array of one element. It is actually `malloc()'ed +with the right size, however, and access to any element through the +`contents' array works fine. + + +File: internals.info, Node: Bit Vector, Next: Symbol, Prev: Vector, Up: Allocation of Objects in XEmacs Lisp + +11.11 Bit Vector +================ + +Bit vectors work exactly like vectors, except for more complicated code +to access an individual bit, and except for the fact that bit vectors +are lrecords while vectors are not. (The only difference here is that +there's an lrecord implementation pointer at the beginning and the tag +field in bit vector Lisp words is "lrecord" rather than "vector".) + + +File: internals.info, Node: Symbol, Next: Marker, Prev: Bit Vector, Up: Allocation of Objects in XEmacs Lisp + +11.12 Symbol +============ + +Symbols are also allocated in frob blocks. Symbols in the awful +horrible obarray structure are chained through their `next' field. + + Remember that `intern' looks up a symbol in an obarray, creating one +if necessary. + + +File: internals.info, Node: Marker, Next: String, Prev: Symbol, Up: Allocation of Objects in XEmacs Lisp + +11.13 Marker +============ + +Markers are allocated in frob blocks, as usual. They are kept in a +buffer unordered, but in a doubly-linked list so that they can easily +be removed. (Formerly this was a singly-linked list, but in some cases +garbage collection took an extraordinarily long time due to the O(N^2) +time required to remove lots of markers from a buffer.) Markers are +removed from a buffer in the finalize stage, in +`ADDITIONAL_FREE_marker()'. + + +File: internals.info, Node: String, Next: Compiled Function, Prev: Marker, Up: Allocation of Objects in XEmacs Lisp + +11.14 String +============ + +As mentioned above, strings are a special case. A string is logically +two parts, a fixed-size object (containing the length, property list, +and a pointer to the actual data), and the actual data in the string. +The fixed-size object is a `struct Lisp_String' and is allocated in +frob blocks, as usual. The actual data is stored in special +"string-chars blocks", which are 8K blocks of memory. +Currently-allocated strings are simply laid end to end in these +string-chars blocks, with a pointer back to the `struct Lisp_String' +stored before each string in the string-chars block. When a new string +needs to be allocated, the remaining space at the end of the last +string-chars block is used if there's enough, and a new string-chars +block is created otherwise. + + There are never any holes in the string-chars blocks due to the +string compaction and relocation that happens at the end of garbage +collection. During the sweep stage of garbage collection, when objects +are reclaimed, the garbage collector goes through all string-chars +blocks, looking for unused strings. Each chunk of string data is +preceded by a pointer to the corresponding `struct Lisp_String', which +indicates both whether the string is used and how big the string is, +i.e. how to get to the next chunk of string data. Holes are compressed +by block-copying the next string into the empty space and relocating the +pointer stored in the corresponding `struct Lisp_String'. *This means +you have to be careful with strings in your code.* See the section +above on `GCPRO'ing. + + Note that there is one situation not handled: a string that is too +big to fit into a string-chars block. Such strings, called "big +strings", are all `malloc()'ed as their own block. (#### Although it +would make more sense for the threshold for big strings to be somewhat +lower, e.g. 1/2 or 1/4 the size of a string-chars block. It seems that +this was indeed the case formerly--indeed, the threshold was set at +1/8--but Mly forgot about this when rewriting things for 19.8.) + + Note also that the string data in string-chars blocks is padded as +necessary so that proper alignment constraints on the `struct +Lisp_String' back pointers are maintained. + + Finally, strings can be resized. This happens in Mule when a +character is substituted with a different-length character, or during +modeline frobbing. (You could also export this to Lisp, but it's not +done so currently.) Resizing a string is a potentially tricky process. +If the change is small enough that the padding can absorb it, nothing +other than a simple memory move needs to be done. Keep in mind, +however, that the string can't shrink too much because the offset to the +next string in the string-chars block is computed by looking at the +length and rounding to the nearest multiple of four or eight. If the +string would shrink or expand beyond the correct padding, new string +data needs to be allocated at the end of the last string-chars block and +the data moved appropriately. This leaves some dead string data, which +is marked by putting a special marker of 0xFFFFFFFF in the `struct +Lisp_String' pointer before the data (there's no real `struct +Lisp_String' to point to and relocate), and storing the size of the dead +string data (which would normally be obtained from the now-non-existent +`struct Lisp_String') at the beginning of the dead string data gap. +The string compactor recognizes this special 0xFFFFFFFF marker and +handles it correctly. + + +File: internals.info, Node: Compiled Function, Prev: String, Up: Allocation of Objects in XEmacs Lisp + +11.15 Compiled Function +======================= + +Not yet documented. + + +File: internals.info, Node: Dumping, Next: Events and the Event Loop, Prev: Allocation of Objects in XEmacs Lisp, Up: Top + +12 Dumping +********** + +12.1 What is dumping and its justification +========================================== + +The C code of XEmacs is just a Lisp engine with a lot of built-in +primitives useful for writing an editor. The editor itself is written +mostly in Lisp, and represents around 100K lines of code. Loading and +executing the initialization of all this code takes a bit a time (five +to ten times the usual startup time of current xemacs) and requires +having all the lisp source files around. Having to reload them each +time the editor is started would not be acceptable. + + The traditional solution to this problem is called dumping: the build +process first creates the lisp engine under the name `temacs', then +runs it until it has finished loading and initializing all the lisp +code, and eventually creates a new executable called `xemacs' including +both the object code in `temacs' and all the contents of the memory +after the initialization. + + This solution, while working, has a huge problem: the creation of the +new executable from the actual contents of memory is an extremely +system-specific process, quite error-prone, and which interferes with a +lot of system libraries (like malloc). It is even getting worse +nowadays with libraries using constructors which are automatically +called when the program is started (even before main()) which tend to +crash when they are called multiple times, once before dumping and once +after (IRIX 6.x libz.so pulls in some C++ image libraries thru +dependencies which have this problem). Writing the dumper is also one +of the most difficult parts of porting XEmacs to a new operating system. +Basically, `dumping' is an operation that is just not officially +supported on many operating systems. + + The aim of the portable dumper is to solve the same problem as the +system-specific dumper, that is to be able to reload quickly, using only +a small number of files, the fully initialized lisp part of the editor, +without any system-specific hacks. + +* Menu: + +* Overview:: +* Data descriptions:: +* Dumping phase:: +* Reloading phase:: +* Remaining issues:: + + +File: internals.info, Node: Overview, Next: Data descriptions, Up: Dumping + +12.2 Overview +============= + +The portable dumping system has to: + + 1. At dump time, write all initialized, non-quickly-rebuildable data + to a file [Note: currently named `xemacs.dmp', but the name will + change], along with all informations needed for the reloading. + + 2. When starting xemacs, reload the dump file, relocate it to its new + starting address if needed, and reinitialize all pointers to this + data. Also, rebuild all the quickly rebuildable data. + + +File: internals.info, Node: Data descriptions, Next: Dumping phase, Prev: Overview, Up: Dumping + +12.3 Data descriptions +====================== + +The more complex task of the dumper is to be able to write lisp objects +(lrecords) and C structs to disk and reload them at a different address, +updating all the pointers they include in the process. This is done by +using external data descriptions that give information about the layout +of the structures in memory. + + The specification of these descriptions is in lrecord.h. A +description of an lrecord is an array of struct lrecord_description. +Each of these structs include a type, an offset in the structure and +some optional parameters depending on the type. For instance, here is +the string description: + + static const struct lrecord_description string_description[] = { + { XD_BYTECOUNT, offsetof (Lisp_String, size) }, + { XD_OPAQUE_DATA_PTR, offsetof (Lisp_String, data), XD_INDIRECT(0, 1) }, + { XD_LISP_OBJECT, offsetof (Lisp_String, plist) }, + { XD_END } + }; + + The first line indicates a member of type Bytecount, which is used by +the next, indirect directive. The second means "there is a pointer to +some opaque data in the field `data'". The length of said data is +given by the expression `XD_INDIRECT(0, 1)', which means "the value in +the 0th line of the description (welcome to C) plus one". The third +line means "there is a Lisp_Object member `plist' in the Lisp_String +structure". `XD_END' then ends the description. + + This gives us all the information we need to move around what is +pointed to by a structure (C or lrecord) and, by transitivity, +everything that it points to. The only missing information for dumping +is the size of the structure. For lrecords, this is part of the +lrecord_implementation, so we don't need to duplicate it. For C +structures we use a struct struct_description, which includes a size +field and a pointer to an associated array of lrecord_description. + + +File: internals.info, Node: Dumping phase, Next: Reloading phase, Prev: Data descriptions, Up: Dumping + +12.4 Dumping phase +================== + +Dumping is done by calling the function pdump() (in dumper.c) which is +invoked from Fdump_emacs (in emacs.c). This function performs a number +of tasks. + +* Menu: + +* Object inventory:: +* Address allocation:: +* The header:: +* Data dumping:: +* Pointers dumping:: + + +File: internals.info, Node: Object inventory, Next: Address allocation, Up: Dumping phase + +12.4.1 Object inventory +----------------------- + +The first task is to build the list of the objects to dump. This +includes: + + * lisp objects + + * C structures + + We end up with one `pdump_entry_list_elmt' per object group (arrays +of C structs are kept together) which includes a pointer to the first +object of the group, the per-object size and the count of objects in the +group, along with some other information which is initialized later. + + These entries are linked together in `pdump_entry_list' structures +and can be enumerated thru either: + + 1. the `pdump_object_table', an array of `pdump_entry_list', one per + lrecord type, indexed by type number. + + 2. the `pdump_opaque_data_list', used for the opaque data which does + not include pointers, and hence does not need descriptions. + + 3. the `pdump_struct_table', which is a vector of + `struct_description'/`pdump_entry_list' pairs, used for non-opaque + C structures. + + This uses a marking strategy similar to the garbage collector. Some +differences though: + + 1. We do not use the mark bit (which does not exist for C structures + anyway); we use a big hash table instead. + + 2. We do not use the mark function of lrecords but instead rely on the + external descriptions. This happens essentially because we need to + follow pointers to C structures and opaque data in addition to + Lisp_Object members. + + This is done by `pdump_register_object()', which handles Lisp_Object +variables, and `pdump_register_struct()' which handles C structures, +which both delegate the description management to +`pdump_register_sub()'. + + The hash table doubles as a map object to pdump_entry_list_elmt (i.e. +allows us to look up a pdump_entry_list_elmt with the object it points +to). Entries are added with `pdump_add_entry()' and looked up with +`pdump_get_entry()'. There is no need for entry removal. The hash +value is computed quite simply from the object pointer by +`pdump_make_hash()'. + + The roots for the marking are: + + 1. the `staticpro''ed variables (there is a special + `staticpro_nodump()' call for protected variables we do not want + to dump). + + 2. the variables registered via `dump_add_root_object' (`staticpro()' + is equivalent to `staticpro_nodump()' + `dump_add_root_object()'). + + 3. the variables registered via `dump_add_root_struct_ptr', each of + which points to a C structure. + + This does not include the GCPRO'ed variables, the specbinds, the +catchtags, the backlist, the redisplay or the profiling info, since we +do not want to rebuild the actual chain of lisp calls which end up to +the dump-emacs call, only the global variables. + + Weak lists and weak hash tables are dumped as if they were their +non-weak equivalent (without changing their type, of course). This has +not yet been a problem. + + +File: internals.info, Node: Address allocation, Next: The header, Prev: Object inventory, Up: Dumping phase + +12.4.2 Address allocation +------------------------- + +The next step is to allocate the offsets of each of the objects in the +final dump file. This is done by `pdump_allocate_offset()' which is +called indirectly by `pdump_scan_by_alignment()'. + + The strategy to deal with alignment problems uses these facts: + + 1. real world alignment requirements are powers of two. + + 2. the C compiler is required to adjust the size of a struct so that + you can have an array of them next to each other. This means you + can have an upper bound of the alignment requirements of a given + structure by looking at which power of two its size is a multiple. + + 3. the non-variant part of variable size lrecords has an alignment + requirement of 4. + + Hence, for each lrecord type, C struct type or opaque data block the +alignment requirement is computed as a power of two, with a minimum of +2^2 for lrecords. `pdump_scan_by_alignment()' then scans all the +`pdump_entry_list_elmt''s, the ones with the highest requirements +first. This ensures the best packing. + + The maximum alignment requirement we take into account is 2^8. + + `pdump_allocate_offset()' only has to do a linear allocation, +starting at offset 256 (this leaves room for the header and keeps the +alignments happy). + + +File: internals.info, Node: The header, Next: Data dumping, Prev: Address allocation, Up: Dumping phase + +12.4.3 The header +----------------- + +The next step creates the file and writes a header with a signature and +some random information in it. The `reloc_address' field, which +indicates at which address the file should be loaded if we want to avoid +post-reload relocation, is set to 0. It then seeks to offset 256 (base +offset for the objects). + + +File: internals.info, Node: Data dumping, Next: Pointers dumping, Prev: The header, Up: Dumping phase + +12.4.4 Data dumping +------------------- + +The data is dumped in the same order as the addresses were allocated by +`pdump_dump_data()', called from `pdump_scan_by_alignment()'. This +function copies the data to a temporary buffer, relocates all pointers +in the object to the addresses allocated in step Address Allocation, +and writes it to the file. Using the same order means that, if we are +careful with lrecords whose size is not a multiple of 4, we are ensured +that the object is always written at the offset in the file allocated +in step Address Allocation. + + +File: internals.info, Node: Pointers dumping, Prev: Data dumping, Up: Dumping phase + +12.4.5 Pointers dumping +----------------------- + +A bunch of tables needed to reassign properly the global pointers are +then written. They are: + + 1. the pdump_root_struct_ptrs dynarr + + 2. the pdump_opaques dynarr + + 3. a vector of all the offsets to the objects in the file that + include a description (for faster relocation at reload time) + + 4. the pdump_root_objects and pdump_weak_object_chains dynarrs. + + For each of the dynarrs we write both the pointer to the variables +and the relocated offset of the object they point to. Since these +variables are global, the pointers are still valid when restarting the +program and are used to regenerate the global pointers. + + The `pdump_weak_object_chains' dynarr is a special case. The +variables it points to are the head of weak linked lists of lisp objects +of the same type. Not all objects of this list are dumped so the +relocated pointer we associate with them points to the first dumped +object of the list, or Qnil if none is available. This is also the +reason why they are not used as roots for the purpose of object +enumeration. + + Some very important information like the `staticpros' and +`lrecord_implementations_table' are handled indirectly using +`dump_add_opaque' or `dump_add_root_struct_ptr'. + + This is the end of the dumping part. + + +File: internals.info, Node: Reloading phase, Next: Remaining issues, Prev: Dumping phase, Up: Dumping + +12.5 Reloading phase +==================== + +12.5.1 File loading +------------------- + +The file is mmap'ed in memory (which ensures a PAGESIZE alignment, at +least 4096), or if mmap is unavailable or fails, a 256-bytes aligned +malloc is done and the file is loaded. + + Some variables are reinitialized from the values found in the header. + + The difference between the actual loading address and the +reloc_address is computed and will be used for all the relocations. + +12.5.2 Putting back the pdump_opaques +------------------------------------- + +The memory contents are restored in the obvious and trivial way. + +12.5.3 Putting back the pdump_root_struct_ptrs +---------------------------------------------- + +The variables pointed to by pdump_root_struct_ptrs in the dump phase are +reset to the right relocated object addresses. + +12.5.4 Object relocation +------------------------ + +All the objects are relocated using their description and their offset +by `pdump_reloc_one'. This step is unnecessary if the reloc_address is +equal to the file loading address. + +12.5.5 Putting back the pdump_root_objects and pdump_weak_object_chains +----------------------------------------------------------------------- + +Same as Putting back the pdump_root_struct_ptrs. + +12.5.6 Reorganize the hash tables +--------------------------------- + +Since some of the hash values in the lisp hash tables are +address-dependent, their layout is now wrong. So we go through each of +them and have them resorted by calling `pdump_reorganize_hash_table'. + + +File: internals.info, Node: Remaining issues, Prev: Reloading phase, Up: Dumping + +12.6 Remaining issues +===================== + +The build process will have to start a post-dump xemacs, ask it the +loading address (which will, hopefully, be always the same between +different xemacs invocations) and relocate the file to the new address. +This way the object relocation phase will not have to be done, which +means no writes in the objects and that, because of the use of mmap, the +dumped data will be shared between all the xemacs running on the +computer. + + Some executable signature will be necessary to ensure that a given +dump file is really associated with a given executable, or random +crashes will occur. Maybe a random number set at compile or configure +time thru a define. This will also allow for having +differently-compiled xemacsen on the same system (mule and no-mule +comes to mind). + + The DOC file contents should probably end up in the dump file. + + +File: internals.info, Node: Events and the Event Loop, Next: Evaluation; Stack Frames; Bindings, Prev: Dumping, Up: Top + +13 Events and the Event Loop +**************************** + +* Menu: + +* Introduction to Events:: +* Main Loop:: +* Specifics of the Event Gathering Mechanism:: +* Specifics About the Emacs Event:: +* The Event Stream Callback Routines:: +* Other Event Loop Functions:: +* Converting Events:: +* Dispatching Events; The Command Builder:: + + +File: internals.info, Node: Introduction to Events, Next: Main Loop, Up: Events and the Event Loop + +13.1 Introduction to Events +=========================== + +An event is an object that encapsulates information about an +interesting occurrence in the operating system. Events are generated +either by user action, direct (e.g. typing on the keyboard or moving +the mouse) or indirect (moving another window, thereby generating an +expose event on an Emacs frame), or as a result of some other typically +asynchronous action happening, such as output from a subprocess being +ready or a timer expiring. Events come into the system in an +asynchronous fashion (typically through a callback being called) and +are converted into a synchronous event queue (first-in, first-out) in a +process that we will call "collection". + + Note that each application has its own event queue. (It is +immaterial whether the collection process directly puts the events in +the proper application's queue, or puts them into a single system +queue, which is later split up.) + + The most basic level of event collection is done by the operating +system or window system. Typically, XEmacs does its own event +collection as well. Often there are multiple layers of collection in +XEmacs, with events from various sources being collected into a queue, +which is then combined with other sources to go into another queue +(i.e. a second level of collection), with perhaps another level on top +of this, etc. + + XEmacs has its own types of events (called "Emacs events"), which +provides an abstract layer on top of the system-dependent nature of the +most basic events that are received. Part of the complex nature of the +XEmacs event collection process involves converting from the +operating-system events into the proper Emacs events--there may not be +a one-to-one correspondence. + + Emacs events are documented in `events.h'; I'll discuss them later. + + +File: internals.info, Node: Main Loop, Next: Specifics of the Event Gathering Mechanism, Prev: Introduction to Events, Up: Events and the Event Loop + +13.2 Main Loop +============== + +The "command loop" is the top-level loop that the editor is always +running. It loops endlessly, calling `next-event' to retrieve an event +and `dispatch-event' to execute it. `dispatch-event' does the +appropriate thing with non-user events (process, timeout, magic, eval, +mouse motion); this involves calling a Lisp handler function, redrawing +a newly-exposed part of a frame, reading subprocess output, etc. For +user events, `dispatch-event' looks up the event in relevant keymaps or +menubars; when a full key sequence or menubar selection is reached, the +appropriate function is executed. `dispatch-event' may have to keep +state across calls; this is done in the "command-builder" structure +associated with each console (remember, there's usually only one +console), and the engine that looks up keystrokes and constructs full +key sequences is called the "command builder". This is documented +elsewhere. + + The guts of the command loop are in `command_loop_1()'. This +function doesn't catch errors, though--that's the job of +`command_loop_2()', which is a condition-case (i.e. error-trapping) +wrapper around `command_loop_1()'. `command_loop_1()' never returns, +but may get thrown out of. + + When an error occurs, `cmd_error()' is called, which usually invokes +the Lisp error handler in `command-error'; however, a default error +handler is provided if `command-error' is `nil' (e.g. during startup). +The purpose of the error handler is simply to display the error message +and do associated cleanup; it does not need to throw anywhere. When +the error handler finishes, the condition-case in `command_loop_2()' +will finish and `command_loop_2()' will reinvoke `command_loop_1()'. + + `command_loop_2()' is invoked from three places: from +`initial_command_loop()' (called from `main()' at the end of internal +initialization), from the Lisp function `recursive-edit', and from +`call_command_loop()'. + + `call_command_loop()' is called when a macro is started and when the +minibuffer is entered; normal termination of the macro or minibuffer +causes a throw out of the recursive command loop. (To +`execute-kbd-macro' for macros and `exit' for minibuffers. Note also +that the low-level minibuffer-entering function, +`read-minibuffer-internal', provides its own error handling and does +not need `command_loop_2()''s error encapsulation; so it tells +`call_command_loop()' to invoke `command_loop_1()' directly.) + + Note that both read-minibuffer-internal and recursive-edit set up a +catch for `exit'; this is why `abort-recursive-edit', which throws to +this catch, exits out of either one. + + `initial_command_loop()', called from `main()', sets up a catch for +`top-level' when invoking `command_loop_2()', allowing functions to +throw all the way to the top level if they really need to. Before +invoking `command_loop_2()', `initial_command_loop()' calls +`top_level_1()', which handles all of the startup stuff (creating the +initial frame, handling the command-line options, loading the user's +`.emacs' file, etc.). The function that actually does this is in Lisp +and is pointed to by the variable `top-level'; normally this function is +`normal-top-level'. `top_level_1()' is just an error-handling wrapper +similar to `command_loop_2()'. Note also that `initial_command_loop()' +sets up a catch for `top-level' when invoking `top_level_1()', just +like when it invokes `command_loop_2()'. + + +File: internals.info, Node: Specifics of the Event Gathering Mechanism, Next: Specifics About the Emacs Event, Prev: Main Loop, Up: Events and the Event Loop + +13.3 Specifics of the Event Gathering Mechanism +=============================================== + +Here is an approximate diagram of the collection processes at work in +XEmacs, under TTY's (TTY's are simpler than X so we'll look at this +first): + + + asynch. asynch. asynch. asynch. [Collectors in + kbd events kbd events process process the OS] + | | output output + | | | | + | | | | SIGINT, [signal handlers + | | | | SIGQUIT, in XEmacs] + V V V V SIGWINCH, + file file file file SIGALRM + desc. desc. desc. desc. | + (TTY) (TTY) (pipe) (pipe) | + | | | | fake timeouts + | | | | file | + | | | | desc. | + | | | | (pipe) | + | | | | | | + | | | | | | + | | | | | | + V V V V V V + ------>-----------<----------------<---------------- + | + | + | [collected using select() in emacs_tty_next_event() + | and converted to the appropriate Emacs event] + | + | + V (above this line is TTY-specific) + Emacs ----------------------------------------------- + event (below this line is the generic event mechanism) + | + | + was there if not, call + a SIGINT? emacs_tty_next_event() + | | + | | + | | + V V + --->------<---- + | + | [collected in event_stream_next_event(); + | SIGINT is converted using maybe_read_quit_event()] + V + Emacs + event + | + \---->------>----- maybe_kbd_translate() ---->---\ + | + | + | + command event queue | + if not from command + (contains events that were event queue, call + read earlier but not processed, event_stream_next_event() + typically when waiting in a | + sit-for, sleep-for, etc. for | + a particular event to be received) | + | | + | | + V V + ---->------------------------------------<---- + | + | [collected in + | next_event_internal()] + | + unread- unread- event from | + command- command- keyboard else, call + events event macro next_event_internal() + | | | | + | | | | + | | | | + V V V V + --------->----------------------<------------ + | + | [collected in `next-event', which may loop + | more than once if the event it gets is on + | a dead frame, device, etc.] + | + | + V + feed into top-level event loop, + which repeatedly calls `next-event' + and then dispatches the event + using `dispatch-event' + + Notice the separation between TTY-specific and generic event +mechanism. When using the Xt-based event loop, the TTY-specific stuff +is replaced but the rest stays the same. + + It's also important to realize that only one different kind of +system-specific event loop can be operating at a time, and must be able +to receive all kinds of events simultaneously. For the two existing +event loops (implemented in `event-tty.c' and `event-Xt.c', +respectively), the TTY event loop _only_ handles TTY consoles, while +the Xt event loop handles _both_ TTY and X consoles. This situation is +different from all of the output handlers, where you simply have one +per console type. + + Here's the Xt Event Loop Diagram (notice that below a certain point, +it's the same as the above diagram): + + asynch. asynch. asynch. asynch. [Collectors in + kbd kbd process process the OS] + events events output output + | | | | + | | | | asynch. asynch. [Collectors in the + | | | | X X OS and X Window System] + | | | | events events + | | | | | | + | | | | | | + | | | | | | SIGINT, [signal handlers + | | | | | | SIGQUIT, in XEmacs] + | | | | | | SIGWINCH, + | | | | | | SIGALRM + | | | | | | | + | | | | | | | + | | | | | | | timeouts + | | | | | | | | + | | | | | | | | + | | | | | | V | + V V V V V V fake | + file file file file file file file | + desc. desc. desc. desc. desc. desc. desc. | + (TTY) (TTY) (pipe) (pipe) (socket) (socket) (pipe) | + | | | | | | | | + | | | | | | | | + | | | | | | | | + V V V V V V V V + --->----------------------------------------<---------<------ + | | | + | | |[collected using select() in + | | | _XtWaitForSomething(), called + | | | from XtAppProcessEvent(), called + | | | in emacs_Xt_next_event(); + | | | dispatched to various callbacks] + | | | + | | | + emacs_Xt_ p_s_callback(), | [popup_selection_callback] + event_handler() x_u_v_s_callback(),| [x_update_vertical_scrollbar_ + | x_u_h_s_callback(),| callback] + | search_callback() | [x_update_horizontal_scrollbar_ + | | | callback] + | | | + | | | + enqueue_Xt_ signal_special_ | + dispatch_event() Xt_user_event() | + [maybe multiple | | + times, maybe 0 | | + times] | | + | enqueue_Xt_ | + | dispatch_event() | + | | | + | | | + V V | + -->----------<-- | + | | + | | + dispatch Xt_what_callback() + event sets flags + queue | + | | + | | + | | + | | + ---->-----------<-------- + | + | + | [collected and converted as appropriate in + | emacs_Xt_next_event()] + | + | + V (above this line is Xt-specific) + Emacs ------------------------------------------------ + event (below this line is the generic event mechanism) + | + | + was there if not, call + a SIGINT? emacs_Xt_next_event() + | | + | | + | | + V V + --->-------<---- + | + | [collected in event_stream_next_event(); + | SIGINT is converted using maybe_read_quit_event()] + V + Emacs + event + | + \---->------>----- maybe_kbd_translate() -->-----\ + | + | + | + command event queue | + if not from command + (contains events that were event queue, call + read earlier but not processed, event_stream_next_event() + typically when waiting in a | + sit-for, sleep-for, etc. for | + a particular event to be received) | + | | + | | + V V + ---->----------------------------------<------ + | + | [collected in + | next_event_internal()] + | + unread- unread- event from | + command- command- keyboard else, call + events event macro next_event_internal() + | | | | + | | | | + | | | | + V V V V + --------->----------------------<------------ + | + | [collected in `next-event', which may loop + | more than once if the event it gets is on + | a dead frame, device, etc.] + | + | + V + feed into top-level event loop, + which repeatedly calls `next-event' + and then dispatches the event + using `dispatch-event' + + +File: internals.info, Node: Specifics About the Emacs Event, Next: The Event Stream Callback Routines, Prev: Specifics of the Event Gathering Mechanism, Up: Events and the Event Loop + +13.4 Specifics About the Emacs Event +==================================== + + +File: internals.info, Node: The Event Stream Callback Routines, Next: Other Event Loop Functions, Prev: Specifics About the Emacs Event, Up: Events and the Event Loop + +13.5 The Event Stream Callback Routines +======================================= + + +File: internals.info, Node: Other Event Loop Functions, Next: Converting Events, Prev: The Event Stream Callback Routines, Up: Events and the Event Loop + +13.6 Other Event Loop Functions +=============================== + +`detect_input_pending()' and `input-pending-p' look for input by +calling `event_stream->event_pending_p' and looking in +`[V]unread-command-event' and the `command_event_queue' (they do not +check for an executing keyboard macro, though). + + `discard-input' cancels any command events pending (and any keyboard +macros currently executing), and puts the others onto the +`command_event_queue'. There is a comment about a "race condition", +which is not a good sign. + + `next-command-event' and `read-char' are higher-level interfaces to +`next-event'. `next-command-event' gets the next "command" event (i.e. +keypress, mouse event, menu selection, or scrollbar action), calling +`dispatch-event' on any others. `read-char' calls `next-command-event' +and uses `event_to_character()' to return the character equivalent. +With the right kind of input method support, it is possible for +(read-char) to return a Kanji character. + + +File: internals.info, Node: Converting Events, Next: Dispatching Events; The Command Builder, Prev: Other Event Loop Functions, Up: Events and the Event Loop + +13.7 Converting Events +====================== + +`character_to_event()', `event_to_character()', `event-to-character', +and `character-to-event' convert between characters and keypress events +corresponding to the characters. If the event was not a keypress, +`event_to_character()' returns -1 and `event-to-character' returns +`nil'. These functions convert between character representation and +the split-up event representation (keysym plus mod keys). + + +File: internals.info, Node: Dispatching Events; The Command Builder, Prev: Converting Events, Up: Events and the Event Loop + +13.8 Dispatching Events; The Command Builder +============================================ + +Not yet documented. + + +File: internals.info, Node: Evaluation; Stack Frames; Bindings, Next: Symbols and Variables, Prev: Events and the Event Loop, Up: Top + +14 Evaluation; Stack Frames; Bindings +************************************* + +* Menu: + +* Evaluation:: +* Dynamic Binding; The specbinding Stack; Unwind-Protects:: +* Simple Special Forms:: +* Catch and Throw:: + + +File: internals.info, Node: Evaluation, Next: Dynamic Binding; The specbinding Stack; Unwind-Protects, Up: Evaluation; Stack Frames; Bindings + +14.1 Evaluation +=============== + +`Feval()' evaluates the form (a Lisp object) that is passed to it. +Note that evaluation is only non-trivial for two types of objects: +symbols and conses. A symbol is evaluated simply by calling +`symbol-value' on it and returning the value. + + Evaluating a cons means calling a function. First, `eval' checks to +see if garbage-collection is necessary, and calls `garbage_collect_1()' +if so. It then increases the evaluation depth by 1 (`lisp_eval_depth', +which is always less than `max_lisp_eval_depth') and adds an element to +the linked list of `struct backtrace''s (`backtrace_list'). Each such +structure contains a pointer to the function being called plus a list +of the function's arguments. Originally these values are stored +unevalled, and as they are evaluated, the backtrace structure is +updated. Garbage collection pays attention to the objects pointed to +in the backtrace structures (garbage collection might happen while a +function is being called or while an argument is being evaluated, and +there could easily be no other references to the arguments in the +argument list; once an argument is evaluated, however, the unevalled +version is not needed by eval, and so the backtrace structure is +changed). + + At this point, the function to be called is determined by looking at +the car of the cons (if this is a symbol, its function definition is +retrieved and the process repeated). The function should then consist +of either a `Lisp_Subr' (built-in function written in C), a +`Lisp_Compiled_Function' object, or a cons whose car is one of the +symbols `autoload', `macro' or `lambda'. + + If the function is a `Lisp_Subr', the lisp object points to a +`struct Lisp_Subr' (created by `DEFUN()'), which contains a pointer to +the C function, a minimum and maximum number of arguments (or possibly +the special constants `MANY' or `UNEVALLED'), a pointer to the symbol +referring to that subr, and a couple of other things. If the subr +wants its arguments `UNEVALLED', they are passed raw as a list. +Otherwise, an array of evaluated arguments is created and put into the +backtrace structure, and either passed whole (`MANY') or each argument +is passed as a C argument. + + If the function is a `Lisp_Compiled_Function', +`funcall_compiled_function()' is called. If the function is a lambda +list, `funcall_lambda()' is called. If the function is a macro, [..... +fill in] is done. If the function is an autoload, `do_autoload()' is +called to load the definition and then eval starts over [explain this +more]. + + When `Feval()' exits, the evaluation depth is reduced by one, the +debugger is called if appropriate, and the current backtrace structure +is removed from the list. + + Both `funcall_compiled_function()' and `funcall_lambda()' need to go +through the list of formal parameters to the function and bind them to +the actual arguments, checking for `&rest' and `&optional' symbols in +the formal parameters and making sure the number of actual arguments is +correct. `funcall_compiled_function()' can do this a little more +efficiently, since the formal parameter list can be checked for sanity +when the compiled function object is created. + + `funcall_lambda()' simply calls `Fprogn' to execute the code in the +lambda list. + + `funcall_compiled_function()' calls the real byte-code interpreter +`execute_optimized_program()' on the byte-code instructions, which are +converted into an internal form for faster execution. + + When a compiled function is executed for the first time by +`funcall_compiled_function()', or during the dump phase of building +XEmacs, the byte-code instructions are converted from a `Lisp_String' +(which is inefficient to access, especially in the presence of MULE) +into a `Lisp_Opaque' object containing an array of unsigned char, which +can be directly executed by the byte-code interpreter. At this time +the byte code is also analyzed for validity and transformed into a more +optimized form, so that `execute_optimized_program()' can really fly. + + Here are some of the optimizations performed by the internal +byte-code transformer: + 1. References to the `constants' array are checked for out-of-range + indices, so that the byte interpreter doesn't have to. + + 2. References to the `constants' array that will be used as a Lisp + variable are checked for being correct non-constant (i.e. not `t', + `nil', or `keywordp') symbols, so that the byte interpreter + doesn't have to. + + 3. The maximum number of variable bindings in the byte-code is + pre-computed, so that space on the `specpdl' stack can be + pre-reserved once for the whole function execution. + + 4. All byte-code jumps are relative to the current program counter + instead of the start of the program, thereby saving a register. + + 5. One-byte relative jumps are converted from the byte-code form of + unsigned chars offset by 127 to machine-friendly signed chars. + + Of course, this transformation of the `instructions' should not be +visible to the user, so `Fcompiled_function_instructions()' needs to +know how to convert the optimized opaque object back into a Lisp string +that is identical to the original string from the `.elc' file. +(Actually, the resulting string may (rarely) contain slightly +different, yet equivalent, byte code.) + + `Ffuncall()' implements Lisp `funcall'. `(funcall fun x1 x2 x3 +...)' is equivalent to `(eval (list fun (quote x1) (quote x2) (quote +x3) ...))'. `Ffuncall()' contains its own code to do the evaluation, +however, and is very similar to `Feval()'. + + From the performance point of view, it is worth knowing that most of +the time in Lisp evaluation is spent executing `Lisp_Subr' and +`Lisp_Compiled_Function' objects via `Ffuncall()' (not `Feval()'). + + `Fapply()' implements Lisp `apply', which is very similar to +`funcall' except that if the last argument is a list, the result is the +same as if each of the arguments in the list had been passed separately. +`Fapply()' does some business to expand the last argument if it's a +list, then calls `Ffuncall()' to do the work. + + `apply1()', `call0()', `call1()', `call2()', and `call3()' call a +function, passing it the argument(s) given (the arguments are given as +separate C arguments rather than being passed as an array). `apply1()' +uses `Fapply()' while the others use `Ffuncall()' to do the real work. + + +File: internals.info, Node: Dynamic Binding; The specbinding Stack; Unwind-Protects, Next: Simple Special Forms, Prev: Evaluation, Up: Evaluation; Stack Frames; Bindings + +14.2 Dynamic Binding; The specbinding Stack; Unwind-Protects +============================================================ + + struct specbinding + { + Lisp_Object symbol; + Lisp_Object old_value; + Lisp_Object (*func) (Lisp_Object); /* for unwind-protect */ + }; + + `struct specbinding' is used for local-variable bindings and +unwind-protects. `specpdl' holds an array of `struct specbinding''s, +`specpdl_ptr' points to the beginning of the free bindings in the +array, `specpdl_size' specifies the total number of binding slots in +the array, and `max_specpdl_size' specifies the maximum number of +bindings the array can be expanded to hold. `grow_specpdl()' increases +the size of the `specpdl' array, multiplying its size by 2 but never +exceeding `max_specpdl_size' (except that if this number is less than +400, it is first set to 400). + + `specbind()' binds a symbol to a value and is used for local +variables and `let' forms. The symbol and its old value (which might +be `Qunbound', indicating no prior value) are recorded in the specpdl +array, and `specpdl_size' is increased by 1. + + `record_unwind_protect()' implements an "unwind-protect", which, +when placed around a section of code, ensures that some specified +cleanup routine will be executed even if the code exits abnormally +(e.g. through a `throw' or quit). `record_unwind_protect()' simply +adds a new specbinding to the `specpdl' array and stores the +appropriate information in it. The cleanup routine can either be a C +function, which is stored in the `func' field, or a `progn' form, which +is stored in the `old_value' field. + + `unbind_to()' removes specbindings from the `specpdl' array until +the specified position is reached. Each specbinding can be one of +three types: + + 1. an unwind-protect with a C cleanup function (`func' is not 0, and + `old_value' holds an argument to be passed to the function); + + 2. an unwind-protect with a Lisp form (`func' is 0, `symbol' is + `nil', and `old_value' holds the form to be executed with + `Fprogn()'); or + + 3. a local-variable binding (`func' is 0, `symbol' is not `nil', and + `old_value' holds the old value, which is stored as the symbol's + value). + + +File: internals.info, Node: Simple Special Forms, Next: Catch and Throw, Prev: Dynamic Binding; The specbinding Stack; Unwind-Protects, Up: Evaluation; Stack Frames; Bindings + +14.3 Simple Special Forms +========================= + +`or', `and', `if', `cond', `progn', `prog1', `prog2', `setq', `quote', +`function', `let*', `let', `while' + + All of these are very simple and work as expected, calling `Feval()' +or `Fprogn()' as necessary and (in the case of `let' and `let*') using +`specbind()' to create bindings and `unbind_to()' to undo the bindings +when finished. + + Note that, with the exception of `Fprogn', these functions are +typically called in real life only in interpreted code, since the byte +compiler knows how to convert calls to these functions directly into +byte code. + diff -u -r -N xemacs-21.4.18/info/internals.info-2 xemacs-21.4.19/info/internals.info-2 --- xemacs-21.4.18/info/internals.info-2 1969-12-31 19:00:00.000000000 -0500 +++ xemacs-21.4.19/info/internals.info-2 2006-01-28 18:57:51.000000000 -0500 @@ -0,0 +1,3145 @@ +This is ../info/internals.info, produced by makeinfo version 4.8 from +internals/internals.texi. + +INFO-DIR-SECTION XEmacs Editor +START-INFO-DIR-ENTRY +* Internals: (internals). XEmacs Internals Manual. +END-INFO-DIR-ENTRY + + Copyright (C) 1992 - 1996 Ben Wing. Copyright (C) 1996, 1997 Sun +Microsystems. Copyright (C) 1994 - 1998, 2002, 2003 Free Software +Foundation. Copyright (C) 1994, 1995 Board of Trustees, University of +Illinois. + + Permission is granted to make and distribute verbatim copies of this +manual provided the copyright notice and this permission notice are +preserved on all copies. + + Permission is granted to copy and distribute modified versions of +this manual under the conditions for verbatim copying, provided that the +entire resulting derived work is distributed under the terms of a +permission notice identical to this one. + + Permission is granted to copy and distribute translations of this +manual into another language, under the above conditions for modified +versions, except that this permission notice may be stated in a +translation approved by the Foundation. + + Permission is granted to copy and distribute modified versions of +this manual under the conditions for verbatim copying, provided also +that the section entitled "GNU General Public License" is included +exactly as in the original, and provided that the entire resulting +derived work is distributed under the terms of a permission notice +identical to this one. + + Permission is granted to copy and distribute translations of this +manual into another language, under the above conditions for modified +versions, except that the section entitled "GNU General Public License" +may be included in a translation approved by the Free Software +Foundation instead of in the original English. + + +File: internals.info, Node: Catch and Throw, Prev: Simple Special Forms, Up: Evaluation; Stack Frames; Bindings + +14.4 Catch and Throw +==================== + + struct catchtag + { + Lisp_Object tag; + Lisp_Object val; + struct catchtag *next; + struct gcpro *gcpro; + jmp_buf jmp; + struct backtrace *backlist; + int lisp_eval_depth; + int pdlcount; + }; + + `catch' is a Lisp function that places a catch around a body of +code. A catch is a means of non-local exit from the code. When a catch +is created, a tag is specified, and executing a `throw' to this tag +will exit from the body of code caught with this tag, and its value will +be the value given in the call to `throw'. If there is no such call, +the code will be executed normally. + + Information pertaining to a catch is held in a `struct catchtag', +which is placed at the head of a linked list pointed to by `catchlist'. +`internal_catch()' is passed a C function to call (`Fprogn()' when +Lisp `catch' is called) and arguments to give it, and places a catch +around the function. Each `struct catchtag' is held in the stack frame +of the `internal_catch()' instance that created the catch. + + `internal_catch()' is fairly straightforward. It stores into the +`struct catchtag' the tag name and the current values of +`backtrace_list', `lisp_eval_depth', `gcprolist', and the offset into +the `specpdl' array, sets a jump point with `_setjmp()' (storing the +jump point into the `struct catchtag'), and calls the function. +Control will return to `internal_catch()' either when the function +exits normally or through a `_longjmp()' to this jump point. In the +latter case, `throw' will store the value to be returned into the +`struct catchtag' before jumping. When it's done, `internal_catch()' +removes the `struct catchtag' from the catchlist and returns the proper +value. + + `Fthrow()' goes up through the catchlist until it finds one with a +matching tag. It then calls `unbind_catch()' to restore everything to +what it was when the appropriate catch was set, stores the return value +in the `struct catchtag', and jumps (with `_longjmp()') to its jump +point. + + `unbind_catch()' removes all catches from the catchlist until it +finds the correct one. Some of the catches might have been placed for +error-trapping, and if so, the appropriate entries on the handlerlist +must be removed (see "errors"). `unbind_catch()' also restores the +values of `gcprolist', `backtrace_list', and `lisp_eval', and calls +`unbind_to()' to undo any specbindings created since the catch. + + +File: internals.info, Node: Symbols and Variables, Next: Buffers and Textual Representation, Prev: Evaluation; Stack Frames; Bindings, Up: Top + +15 Symbols and Variables +************************ + +* Menu: + +* Introduction to Symbols:: +* Obarrays:: +* Symbol Values:: + + +File: internals.info, Node: Introduction to Symbols, Next: Obarrays, Up: Symbols and Variables + +15.1 Introduction to Symbols +============================ + +A symbol is basically just an object with four fields: a name (a +string), a value (some Lisp object), a function (some Lisp object), and +a property list (usually a list of alternating keyword/value pairs). +What makes symbols special is that there is usually only one symbol with +a given name, and the symbol is referred to by name. This makes a +symbol a convenient way of calling up data by name, i.e. of implementing +variables. (The variable's value is stored in the "value slot".) +Similarly, functions are referenced by name, and the definition of the +function is stored in a symbol's "function slot". This means that +there can be a distinct function and variable with the same name. The +property list is used as a more general mechanism of associating +additional values with particular names, and once again the namespace is +independent of the function and variable namespaces. + + +File: internals.info, Node: Obarrays, Next: Symbol Values, Prev: Introduction to Symbols, Up: Symbols and Variables + +15.2 Obarrays +============= + +The identity of symbols with their names is accomplished through a +structure called an obarray, which is just a poorly-implemented hash +table mapping from strings to symbols whose name is that string. (I say +"poorly implemented" because an obarray appears in Lisp as a vector +with some hidden fields rather than as its own opaque type. This is an +Emacs Lisp artifact that should be fixed.) + + Obarrays are implemented as a vector of some fixed size (which should +be a prime for best results), where each "bucket" of the vector +contains one or more symbols, threaded through a hidden `next' field in +the symbol. Lookup of a symbol in an obarray, and adding a symbol to +an obarray, is accomplished through standard hash-table techniques. + + The standard Lisp function for working with symbols and obarrays is +`intern'. This looks up a symbol in an obarray given its name; if it's +not found, a new symbol is automatically created with the specified +name, added to the obarray, and returned. This is what happens when the +Lisp reader encounters a symbol (or more precisely, encounters the name +of a symbol) in some text that it is reading. There is a standard +obarray called `obarray' that is used for this purpose, although the +Lisp programmer is free to create his own obarrays and `intern' symbols +in them. + + Note that, once a symbol is in an obarray, it stays there until +something is done about it, and the standard obarray `obarray' always +stays around, so once you use any particular variable name, a +corresponding symbol will stay around in `obarray' until you exit +XEmacs. + + Note that `obarray' itself is a variable, and as such there is a +symbol in `obarray' whose name is `"obarray"' and which contains +`obarray' as its value. + + Note also that this call to `intern' occurs only when in the Lisp +reader, not when the code is executed (at which point the symbol is +already around, stored as such in the definition of the function). + + You can create your own obarray using `make-vector' (this is +horrible but is an artifact) and intern symbols into that obarray. +Doing that will result in two or more symbols with the same name. +However, at most one of these symbols is in the standard `obarray': You +cannot have two symbols of the same name in any particular obarray. +Note that you cannot add a symbol to an obarray in any fashion other +than using `intern': i.e. you can't take an existing symbol and put it +in an existing obarray. Nor can you change the name of an existing +symbol. (Since obarrays are vectors, you can violate the consistency of +things by storing directly into the vector, but let's ignore that +possibility.) + + Usually symbols are created by `intern', but if you really want, you +can explicitly create a symbol using `make-symbol', giving it some +name. The resulting symbol is not in any obarray (i.e. it is +"uninterned"), and you can't add it to any obarray. Therefore its +primary purpose is as a symbol to use in macros to avoid namespace +pollution. It can also be used as a carrier of information, but cons +cells could probably be used just as well. + + You can also use `intern-soft' to look up a symbol but not create a +new one, and `unintern' to remove a symbol from an obarray. This +returns the removed symbol. (Remember: You can't put the symbol back +into any obarray.) Finally, `mapatoms' maps over all of the symbols in +an obarray. + + +File: internals.info, Node: Symbol Values, Prev: Obarrays, Up: Symbols and Variables + +15.3 Symbol Values +================== + +The value field of a symbol normally contains a Lisp object. However, +a symbol can be "unbound", meaning that it logically has no value. +This is internally indicated by storing a special Lisp object, called +"the unbound marker" and stored in the global variable `Qunbound'. The +unbound marker is of a special Lisp object type called +"symbol-value-magic". It is impossible for the Lisp programmer to +directly create or access any object of this type. + + *You must not let any "symbol-value-magic" object escape to the Lisp +level.* Printing any of these objects will cause the message `INTERNAL +EMACS BUG' to appear as part of the print representation. (You may see +this normally when you call `debug_print()' from the debugger on a Lisp +object.) If you let one of these objects escape to the Lisp level, you +will violate a number of assumptions contained in the C code and make +the unbound marker not function right. + + When a symbol is created, its value field (and function field) are +set to `Qunbound'. The Lisp programmer can restore these conditions +later using `makunbound' or `fmakunbound', and can query to see whether +the value of function fields are "bound" (i.e. have a value other than +`Qunbound') using `boundp' and `fboundp'. The fields are set to a +normal Lisp object using `set' (or `setq') and `fset'. + + Other symbol-value-magic objects are used as special markers to +indicate variables that have non-normal properties. This includes any +variables that are tied into C variables (setting the variable magically +sets some global variable in the C code, and likewise for retrieving the +variable's value), variables that magically tie into slots in the +current buffer, variables that are buffer-local, etc. The +symbol-value-magic object is stored in the value cell in place of a +normal object, and the code to retrieve a symbol's value (i.e. +`symbol-value') knows how to do special things with them. This means +that you should not just fetch the value cell directly if you want a +symbol's value. + + The exact workings of this are rather complex and involved and are +well-documented in comments in `buffer.c', `symbols.c', and `lisp.h'. + + +File: internals.info, Node: Buffers and Textual Representation, Next: MULE Character Sets and Encodings, Prev: Symbols and Variables, Up: Top + +16 Buffers and Textual Representation +************************************* + +* Menu: + +* Introduction to Buffers:: A buffer holds a block of text such as a file. +* The Text in a Buffer:: Representation of the text in a buffer. +* Buffer Lists:: Keeping track of all buffers. +* Markers and Extents:: Tagging locations within a buffer. +* Bufbytes and Emchars:: Representation of individual characters. +* The Buffer Object:: The Lisp object corresponding to a buffer. + + +File: internals.info, Node: Introduction to Buffers, Next: The Text in a Buffer, Up: Buffers and Textual Representation + +16.1 Introduction to Buffers +============================ + +A buffer is logically just a Lisp object that holds some text. In +this, it is like a string, but a buffer is optimized for frequent +insertion and deletion, while a string is not. Furthermore: + + 1. Buffers are "permanent" objects, i.e. once you create them, they + remain around, and need to be explicitly deleted before they go + away. + + 2. Each buffer has a unique name, which is a string. Buffers are + normally referred to by name. In this respect, they are like + symbols. + + 3. Buffers have a default insertion position, called "point". + Inserting text (unless you explicitly give a position) goes at + point, and moves point forward past the text. This is what is + going on when you type text into Emacs. + + 4. Buffers have lots of extra properties associated with them. + + 5. Buffers can be "displayed". What this means is that there exist a + number of "windows", which are objects that correspond to some + visible section of your display, and each window has an associated + buffer, and the current contents of the buffer are shown in that + section of the display. The redisplay mechanism (which takes care + of doing this) knows how to look at the text of a buffer and come + up with some reasonable way of displaying this. Many of the + properties of a buffer control how the buffer's text is displayed. + + 6. One buffer is distinguished and called the "current buffer". It is + stored in the variable `current_buffer'. Buffer operations operate + on this buffer by default. When you are typing text into a + buffer, the buffer you are typing into is always `current_buffer'. + Switching to a different window changes the current buffer. Note + that Lisp code can temporarily change the current buffer using + `set-buffer' (often enclosed in a `save-excursion' so that the + former current buffer gets restored when the code is finished). + However, calling `set-buffer' will NOT cause a permanent change in + the current buffer. The reason for this is that the top-level + event loop sets `current_buffer' to the buffer of the selected + window, each time it finishes executing a user command. + + Make sure you understand the distinction between "current buffer" +and "buffer of the selected window", and the distinction between +"point" of the current buffer and "window-point" of the selected +window. (This latter distinction is explained in detail in the section +on windows.) + + +File: internals.info, Node: The Text in a Buffer, Next: Buffer Lists, Prev: Introduction to Buffers, Up: Buffers and Textual Representation + +16.2 The Text in a Buffer +========================= + +The text in a buffer consists of a sequence of zero or more characters. +A "character" is an integer that logically represents a letter, +number, space, or other unit of text. Most of the characters that you +will typically encounter belong to the ASCII set of characters, but +there are also characters for various sorts of accented letters, +special symbols, Chinese and Japanese ideograms (i.e. Kanji, Katakana, +etc.), Cyrillic and Greek letters, etc. The actual number of possible +characters is quite large. + + For now, we can view a character as some non-negative integer that +has some shape that defines how it typically appears (e.g. as an +uppercase A). (The exact way in which a character appears depends on the +font used to display the character.) The internal type of characters in +the C code is an `Emchar'; this is just an `int', but using a symbolic +type makes the code clearer. + + Between every character in a buffer is a "buffer position" or +"character position". We can speak of the character before or after a +particular buffer position, and when you insert a character at a +particular position, all characters after that position end up at new +positions. When we speak of the character "at" a position, we really +mean the character after the position. (This schizophrenia between a +buffer position being "between" a character and "on" a character is +rampant in Emacs.) + + Buffer positions are numbered starting at 1. This means that +position 1 is before the first character, and position 0 is not valid. +If there are N characters in a buffer, then buffer position N+1 is +after the last one, and position N+2 is not valid. + + The internal makeup of the Emchar integer varies depending on whether +we have compiled with MULE support. If not, the Emchar integer is an +8-bit integer with possible values from 0 - 255. 0 - 127 are the +standard ASCII characters, while 128 - 255 are the characters from the +ISO-8859-1 character set. If we have compiled with MULE support, an +Emchar is a 19-bit integer, with the various bits having meanings +according to a complex scheme that will be detailed later. The +characters numbered 0 - 255 still have the same meanings as for the +non-MULE case, though. + + Internally, the text in a buffer is represented in a fairly simple +fashion: as a contiguous array of bytes, with a "gap" of some size in +the middle. Although the gap is of some substantial size in bytes, +there is no text contained within it: From the perspective of the text +in the buffer, it does not exist. The gap logically sits at some buffer +position, between two characters (or possibly at the beginning or end of +the buffer). Insertion of text in a buffer at a particular position is +always accomplished by first moving the gap to that position (i.e. +through some block moving of text), then writing the text into the +beginning of the gap, thereby shrinking the gap. If the gap shrinks +down to nothing, a new gap is created. (What actually happens is that a +new gap is "created" at the end of the buffer's text, which requires +nothing more than changing a couple of indices; then the gap is "moved" +to the position where the insertion needs to take place by moving up in +memory all the text after that position.) Similarly, deletion occurs +by moving the gap to the place where the text is to be deleted, and +then simply expanding the gap to include the deleted text. +("Expanding" and "shrinking" the gap as just described means just that +the internal indices that keep track of where the gap is located are +changed.) + + Note that the total amount of memory allocated for a buffer text +never decreases while the buffer is live. Therefore, if you load up a +20-megabyte file and then delete all but one character, there will be a +20-megabyte gap, which won't get any smaller (except by inserting +characters back again). Once the buffer is killed, the memory allocated +for the buffer text will be freed, but it will still be sitting on the +heap, taking up virtual memory, and will not be released back to the +operating system. (However, if you have compiled XEmacs with rel-alloc, +the situation is different. In this case, the space _will_ be released +back to the operating system. However, this tends to result in a +noticeable speed penalty.) + + Astute readers may notice that the text in a buffer is represented as +an array of _bytes_, while (at least in the MULE case) an Emchar is a +19-bit integer, which clearly cannot fit in a byte. This means (of +course) that the text in a buffer uses a different representation from +an Emchar: specifically, the 19-bit Emchar becomes a series of one to +four bytes. The conversion between these two representations is complex +and will be described later. + + In the non-MULE case, everything is very simple: An Emchar is an +8-bit value, which fits neatly into one byte. + + If we are given a buffer position and want to retrieve the character +at that position, we need to follow these steps: + + 1. Pretend there's no gap, and convert the buffer position into a + "byte index" that indexes to the appropriate byte in the buffer's + stream of textual bytes. By convention, byte indices begin at 1, + just like buffer positions. In the non-MULE case, byte indices + and buffer positions are identical, since one character equals one + byte. + + 2. Convert the byte index into a "memory index", which takes the gap + into account. The memory index is a direct index into the block of + memory that stores the text of a buffer. This basically just + involves checking to see if the byte index is past the gap, and if + so, adding the size of the gap to it. By convention, memory + indices begin at 1, just like buffer positions and byte indices, + and when referring to the position that is "at" the gap, we always + use the memory position at the _beginning_, not at the end, of the + gap. + + 3. Fetch the appropriate bytes at the determined memory position. + + 4. Convert these bytes into an Emchar. + + In the non-Mule case, (3) and (4) boil down to a simple one-byte +memory access. + + Note that we have defined three types of positions in a buffer: + + 1. "buffer positions" or "character positions", typedef `Bufpos' + + 2. "byte indices", typedef `Bytind' + + 3. "memory indices", typedef `Memind' + + All three typedefs are just `int's, but defining them this way makes +things a lot clearer. + + Most code works with buffer positions. In particular, all Lisp code +that refers to text in a buffer uses buffer positions. Lisp code does +not know that byte indices or memory indices exist. + + Finally, we have a typedef for the bytes in a buffer. This is a +`Bufbyte', which is an unsigned char. Referring to them as Bufbytes +underscores the fact that we are working with a string of bytes in the +internal Emacs buffer representation rather than in one of a number of +possible alternative representations (e.g. EUC-encoded text, etc.). + + +File: internals.info, Node: Buffer Lists, Next: Markers and Extents, Prev: The Text in a Buffer, Up: Buffers and Textual Representation + +16.3 Buffer Lists +================= + +Recall earlier that buffers are "permanent" objects, i.e. that they +remain around until explicitly deleted. This entails that there is a +list of all the buffers in existence. This list is actually an +assoc-list (mapping from the buffer's name to the buffer) and is stored +in the global variable `Vbuffer_alist'. + + The order of the buffers in the list is important: the buffers are +ordered approximately from most-recently-used to least-recently-used. +Switching to a buffer using `switch-to-buffer', `pop-to-buffer', etc. +and switching windows using `other-window', etc. usually brings the +new current buffer to the front of the list. `switch-to-buffer', +`other-buffer', etc. look at the beginning of the list to find an +alternative buffer to suggest. You can also explicitly move a buffer +to the end of the list using `bury-buffer'. + + In addition to the global ordering in `Vbuffer_alist', each frame +has its own ordering of the list. These lists always contain the same +elements as in `Vbuffer_alist' although possibly in a different order. +`buffer-list' normally returns the list for the selected frame. This +allows you to work in separate frames without things interfering with +each other. + + The standard way to look up a buffer given a name is `get-buffer', +and the standard way to create a new buffer is `get-buffer-create', +which looks up a buffer with a given name, creating a new one if +necessary. These operations correspond exactly with the symbol +operations `intern-soft' and `intern', respectively. You can also +force a new buffer to be created using `generate-new-buffer', which +takes a name and (if necessary) makes a unique name from this by +appending a number, and then creates the buffer. This is basically +like the symbol operation `gensym'. + + +File: internals.info, Node: Markers and Extents, Next: Bufbytes and Emchars, Prev: Buffer Lists, Up: Buffers and Textual Representation + +16.4 Markers and Extents +======================== + +Among the things associated with a buffer are things that are logically +attached to certain buffer positions. This can be used to keep track +of a buffer position when text is inserted and deleted, so that it +remains at the same spot relative to the text around it; to assign +properties to particular sections of text; etc. There are two such +objects that are useful in this regard: they are "markers" and +"extents". + + A "marker" is simply a flag placed at a particular buffer position, +which is moved around as text is inserted and deleted. Markers are +used for all sorts of purposes, such as the `mark' that is the other +end of textual regions to be cut, copied, etc. + + An "extent" is similar to two markers plus some associated +properties, and is used to keep track of regions in a buffer as text is +inserted and deleted, and to add properties (e.g. fonts) to particular +regions of text. The external interface of extents is explained +elsewhere. + + The important thing here is that markers and extents simply contain +buffer positions in them as integers, and every time text is inserted or +deleted, these positions must be updated. In order to minimize the +amount of shuffling that needs to be done, the positions in markers and +extents (there's one per marker, two per extent) are stored in Meminds. +This means that they only need to be moved when the text is physically +moved in memory; since the gap structure tries to minimize this, it also +minimizes the number of marker and extent indices that need to be +adjusted. Look in `insdel.c' for the details of how this works. + + One other important distinction is that markers are "temporary" +while extents are "permanent". This means that markers disappear as +soon as there are no more pointers to them, and correspondingly, there +is no way to determine what markers are in a buffer if you are just +given the buffer. Extents remain in a buffer until they are detached +(which could happen as a result of text being deleted) or the buffer is +deleted, and primitives do exist to enumerate the extents in a buffer. + + +File: internals.info, Node: Bufbytes and Emchars, Next: The Buffer Object, Prev: Markers and Extents, Up: Buffers and Textual Representation + +16.5 Bufbytes and Emchars +========================= + +Not yet documented. + + +File: internals.info, Node: The Buffer Object, Prev: Bufbytes and Emchars, Up: Buffers and Textual Representation + +16.6 The Buffer Object +====================== + +Buffers contain fields not directly accessible by the Lisp programmer. +We describe them here, naming them by the names used in the C code. +Many are accessible indirectly in Lisp programs via Lisp primitives. + +`name' + The buffer name is a string that names the buffer. It is + guaranteed to be unique. *Note Buffer Names: (lispref)Buffer + Names. + +`save_modified' + This field contains the time when the buffer was last saved, as an + integer. *Note Buffer Modification: (lispref)Buffer Modification. + +`modtime' + This field contains the modification time of the visited file. It + is set when the file is written or read. Every time the buffer is + written to the file, this field is compared to the modification + time of the file. *Note Buffer Modification: (lispref)Buffer + Modification. + +`auto_save_modified' + This field contains the time when the buffer was last auto-saved. + +`last_window_start' + This field contains the `window-start' position in the buffer as of + the last time the buffer was displayed in a window. + +`undo_list' + This field points to the buffer's undo list. *Note Undo: + (lispref)Undo. + +`syntax_table_v' + This field contains the syntax table for the buffer. *Note Syntax + Tables: (lispref)Syntax Tables. + +`downcase_table' + This field contains the conversion table for converting text to + lower case. *Note Case Tables: (lispref)Case Tables. + +`upcase_table' + This field contains the conversion table for converting text to + upper case. *Note Case Tables: (lispref)Case Tables. + +`case_canon_table' + This field contains the conversion table for canonicalizing text + for case-folding search. *Note Case Tables: (lispref)Case Tables. + +`case_eqv_table' + This field contains the equivalence table for case-folding search. + *Note Case Tables: (lispref)Case Tables. + +`display_table' + This field contains the buffer's display table, or `nil' if it + doesn't have one. *Note Display Tables: (lispref)Display Tables. + +`markers' + This field contains the chain of all markers that currently point + into the buffer. Deletion of text in the buffer, and motion of + the buffer's gap, must check each of these markers and perhaps + update it. *Note Markers: (lispref)Markers. + +`backed_up' + This field is a flag that tells whether a backup file has been + made for the visited file of this buffer. + +`mark' + This field contains the mark for the buffer. The mark is a marker, + hence it is also included on the list `markers'. *Note The Mark: + (lispref)The Mark. + +`mark_active' + This field is non-`nil' if the buffer's mark is active. + +`local_var_alist' + This field contains the association list describing the variables + local in this buffer, and their values, with the exception of + local variables that have special slots in the buffer object. + (Those slots are omitted from this table.) *Note Buffer-Local + Variables: (lispref)Buffer-Local Variables. + +`modeline_format' + This field contains a Lisp object which controls how to display + the mode line for this buffer. *Note Modeline Format: + (lispref)Modeline Format. + +`base_buffer' + This field holds the buffer's base buffer (if it is an indirect + buffer), or `nil'. + + +File: internals.info, Node: MULE Character Sets and Encodings, Next: The Lisp Reader and Compiler, Prev: Buffers and Textual Representation, Up: Top + +17 MULE Character Sets and Encodings +************************************ + +Recall that there are two primary ways that text is represented in +XEmacs. The "buffer" representation sees the text as a series of bytes +(Bufbytes), with a variable number of bytes used per character. The +"character" representation sees the text as a series of integers +(Emchars), one per character. The character representation is a cleaner +representation from a theoretical standpoint, and is thus used in many +cases when lots of manipulations on a string need to be done. However, +the buffer representation is the standard representation used in both +Lisp strings and buffers, and because of this, it is the "default" +representation that text comes in. The reason for using this +representation is that it's compact and is compatible with ASCII. + +* Menu: + +* Character Sets:: +* Encodings:: +* Internal Mule Encodings:: +* CCL:: + + +File: internals.info, Node: Character Sets, Next: Encodings, Up: MULE Character Sets and Encodings + +17.1 Character Sets +=================== + +A character set (or "charset") is an ordered set of characters. A +particular character in a charset is indexed using one or more +"position codes", which are non-negative integers. The number of +position codes needed to identify a particular character in a charset is +called the "dimension" of the charset. In XEmacs/Mule, all charsets +have dimension 1 or 2, and the size of all charsets (except for a few +special cases) is either 94, 96, 94 by 94, or 96 by 96. The range of +position codes used to index characters from any of these types of +character sets is as follows: + + Charset type Position code 1 Position code 2 + ------------------------------------------------------------ + 94 33 - 126 N/A + 96 32 - 127 N/A + 94x94 33 - 126 33 - 126 + 96x96 32 - 127 32 - 127 + + Note that in the above cases position codes do not start at an +expected value such as 0 or 1. The reason for this will become clear +later. + + For example, Latin-1 is a 96-character charset, and JISX0208 (the +Japanese national character set) is a 94x94-character charset. + + [Note that, although the ranges above define the _valid_ position +codes for a charset, some of the slots in a particular charset may in +fact be empty. This is the case for JISX0208, for example, where (e.g.) +all the slots whose first position code is in the range 118 - 127 are +empty.] + + There are three charsets that do not follow the above rules. All of +them have one dimension, and have ranges of position codes as follows: + + Charset name Position code 1 + ------------------------------------ + ASCII 0 - 127 + Control-1 0 - 31 + Composite 0 - some large number + + (The upper bound of the position code for composite characters has +not yet been determined, but it will probably be at least 16,383). + + ASCII is the union of two subsidiary character sets: Printing-ASCII +(the printing ASCII character set, consisting of position codes 33 - +126, like for a standard 94-character charset) and Control-ASCII (the +non-printing characters that would appear in a binary file with codes 0 +- 32 and 127). + + Control-1 contains the non-printing characters that would appear in a +binary file with codes 128 - 159. + + Composite contains characters that are generated by overstriking one +or more characters from other charsets. + + Note that some characters in ASCII, and all characters in Control-1, +are "control" (non-printing) characters. These have no printed +representation but instead control some other function of the printing +(e.g. TAB or 8 moves the current character position to the next tab +stop). All other characters in all charsets are "graphic" (printing) +characters. + + When a binary file is read in, the bytes in the file are assigned to +character sets as follows: + + Bytes Character set Range + -------------------------------------------------- + 0 - 127 ASCII 0 - 127 + 128 - 159 Control-1 0 - 31 + 160 - 255 Latin-1 32 - 127 + + This is a bit ad-hoc but gets the job done. + + +File: internals.info, Node: Encodings, Next: Internal Mule Encodings, Prev: Character Sets, Up: MULE Character Sets and Encodings + +17.2 Encodings +============== + +An "encoding" is a way of numerically representing characters from one +or more character sets. If an encoding only encompasses one character +set, then the position codes for the characters in that character set +could be used directly. This is not possible, however, if more than +one character set is to be used in the encoding. + + For example, the conversion detailed above between bytes in a binary +file and characters is effectively an encoding that encompasses the +three character sets ASCII, Control-1, and Latin-1 in a stream of 8-bit +bytes. + + Thus, an encoding can be viewed as a way of encoding characters from +a specified group of character sets using a stream of bytes, each of +which contains a fixed number of bits (but not necessarily 8, as in the +common usage of "byte"). + + Here are descriptions of a couple of common encodings: + +* Menu: + +* Japanese EUC (Extended Unix Code):: +* JIS7:: + + +File: internals.info, Node: Japanese EUC (Extended Unix Code), Next: JIS7, Up: Encodings + +17.2.1 Japanese EUC (Extended Unix Code) +---------------------------------------- + +This encompasses the character sets Printing-ASCII, Japanese-JISX0201, +and Japanese-JISX0208-Kana (half-width katakana, the right half of +JISX0201). It uses 8-bit bytes. + + Note that Printing-ASCII and Japanese-JISX0201-Kana are 94-character +charsets, while Japanese-JISX0208 is a 94x94-character charset. + + The encoding is as follows: + + Character set Representation (PC=position-code) + ------------- -------------- + Printing-ASCII PC1 + Japanese-JISX0201-Kana 0x8E | PC1 + 0x80 + Japanese-JISX0208 PC1 + 0x80 | PC2 + 0x80 + Japanese-JISX0212 PC1 + 0x80 | PC2 + 0x80 + + +File: internals.info, Node: JIS7, Prev: Japanese EUC (Extended Unix Code), Up: Encodings + +17.2.2 JIS7 +----------- + +This encompasses the character sets Printing-ASCII, +Japanese-JISX0201-Roman (the left half of JISX0201; this character set +is very similar to Printing-ASCII and is a 94-character charset), +Japanese-JISX0208, and Japanese-JISX0201-Kana. It uses 7-bit bytes. + + Unlike Japanese EUC, this is a "modal" encoding, which means that +there are multiple states that the encoding can be in, which affect how +the bytes are to be interpreted. Special sequences of bytes (called +"escape sequences") are used to change states. + + The encoding is as follows: + + Character set Representation (PC=position-code) + ------------- -------------- + Printing-ASCII PC1 + Japanese-JISX0201-Roman PC1 + Japanese-JISX0201-Kana PC1 + Japanese-JISX0208 PC1 PC2 + + + Escape sequence ASCII equivalent Meaning + --------------- ---------------- ------- + 0x1B 0x28 0x4A ESC ( J invoke Japanese-JISX0201-Roman + 0x1B 0x28 0x49 ESC ( I invoke Japanese-JISX0201-Kana + 0x1B 0x24 0x42 ESC $ B invoke Japanese-JISX0208 + 0x1B 0x28 0x42 ESC ( B invoke Printing-ASCII + + Initially, Printing-ASCII is invoked. + + +File: internals.info, Node: Internal Mule Encodings, Next: CCL, Prev: Encodings, Up: MULE Character Sets and Encodings + +17.3 Internal Mule Encodings +============================ + +In XEmacs/Mule, each character set is assigned a unique number, called a +"leading byte". This is used in the encodings of a character. Leading +bytes are in the range 0x80 - 0xFF (except for ASCII, which has a +leading byte of 0), although some leading bytes are reserved. + + Charsets whose leading byte is in the range 0x80 - 0x9F are called +"official" and are used for built-in charsets. Other charsets are +called "private" and have leading bytes in the range 0xA0 - 0xFF; these +are user-defined charsets. + + More specifically: + + Character set Leading byte + ------------- ------------ + ASCII 0 + Composite 0x80 + Dimension-1 Official 0x81 - 0x8D + (0x8E is free) + Control-1 0x8F + Dimension-2 Official 0x90 - 0x99 + (0x9A - 0x9D are free; + 0x9E and 0x9F are reserved) + Dimension-1 Private 0xA0 - 0xEF + Dimension-2 Private 0xF0 - 0xFF + + There are two internal encodings for characters in XEmacs/Mule. One +is called "string encoding" and is an 8-bit encoding that is used for +representing characters in a buffer or string. It uses 1 to 4 bytes per +character. The other is called "character encoding" and is a 19-bit +encoding that is used for representing characters individually in a +variable. + + (In the following descriptions, we'll ignore composite characters for +the moment. We also give a general (structural) overview first, +followed later by the exact details.) + +* Menu: + +* Internal String Encoding:: +* Internal Character Encoding:: + + +File: internals.info, Node: Internal String Encoding, Next: Internal Character Encoding, Up: Internal Mule Encodings + +17.3.1 Internal String Encoding +------------------------------- + +ASCII characters are encoded using their position code directly. Other +characters are encoded using their leading byte followed by their +position code(s) with the high bit set. Characters in private character +sets have their leading byte prefixed with a "leading byte prefix", +which is either 0x9E or 0x9F. (No character sets are ever assigned these +leading bytes.) Specifically: + + Character set Encoding (PC=position-code, LB=leading-byte) + ------------- -------- + ASCII PC-1 | + Control-1 LB | PC1 + 0xA0 | + Dimension-1 official LB | PC1 + 0x80 | + Dimension-1 private 0x9E | LB | PC1 + 0x80 | + Dimension-2 official LB | PC1 + 0x80 | PC2 + 0x80 | + Dimension-2 private 0x9F | LB | PC1 + 0x80 | PC2 + 0x80 + + The basic characteristic of this encoding is that the first byte of +all characters is in the range 0x00 - 0x9F, and the second and +following bytes of all characters is in the range 0xA0 - 0xFF. This +means that it is impossible to get out of sync, or more specifically: + + 1. Given any byte position, the beginning of the character it is + within can be determined in constant time. + + 2. Given any byte position at the beginning of a character, the + beginning of the next character can be determined in constant time. + + 3. Given any byte position at the beginning of a character, the + beginning of the previous character can be determined in constant + time. + + 4. Textual searches can simply treat encoded strings as if they were + encoded in a one-byte-per-character fashion rather than the actual + multi-byte encoding. + + None of the standard non-modal encodings meet all of these +conditions. For example, EUC satisfies only (2) and (3), while +Shift-JIS and Big5 (not yet described) satisfy only (2). (All non-modal +encodings must satisfy (2), in order to be unambiguous.) + + +File: internals.info, Node: Internal Character Encoding, Prev: Internal String Encoding, Up: Internal Mule Encodings + +17.3.2 Internal Character Encoding +---------------------------------- + +One 19-bit word represents a single character. The word is separated +into three fields: + + Bit number: 18 17 16 15 14 13 12 11 10 09 08 07 06 05 04 03 02 01 00 + <------------> <------------------> <------------------> + Field: 1 2 3 + + Note that fields 2 and 3 hold 7 bits each, while field 1 holds 5 +bits. + + Character set Field 1 Field 2 Field 3 + ------------- ------- ------- ------- + ASCII 0 0 PC1 + range: (00 - 7F) + Control-1 0 1 PC1 + range: (00 - 1F) + Dimension-1 official 0 LB - 0x80 PC1 + range: (01 - 0D) (20 - 7F) + Dimension-1 private 0 LB - 0x80 PC1 + range: (20 - 6F) (20 - 7F) + Dimension-2 official LB - 0x8F PC1 PC2 + range: (01 - 0A) (20 - 7F) (20 - 7F) + Dimension-2 private LB - 0xE1 PC1 PC2 + range: (0F - 1E) (20 - 7F) (20 - 7F) + Composite 0x1F ? ? + + Note that character codes 0 - 255 are the same as the "binary +encoding" described above. + + +File: internals.info, Node: CCL, Prev: Internal Mule Encodings, Up: MULE Character Sets and Encodings + +17.4 CCL +======== + + CCL PROGRAM SYNTAX: + CCL_PROGRAM := (CCL_MAIN_BLOCK + [ CCL_EOF_BLOCK ]) + + CCL_MAIN_BLOCK := CCL_BLOCK + CCL_EOF_BLOCK := CCL_BLOCK + + CCL_BLOCK := STATEMENT | (STATEMENT [STATEMENT ...]) + STATEMENT := + SET | IF | BRANCH | LOOP | REPEAT | BREAK + | READ | WRITE + + SET := (REG = EXPRESSION) | (REG SELF_OP EXPRESSION) + | INT-OR-CHAR + + EXPRESSION := ARG | (EXPRESSION OP ARG) + + IF := (if EXPRESSION CCL_BLOCK CCL_BLOCK) + BRANCH := (branch EXPRESSION CCL_BLOCK [CCL_BLOCK ...]) + LOOP := (loop STATEMENT [STATEMENT ...]) + BREAK := (break) + REPEAT := (repeat) + | (write-repeat [REG | INT-OR-CHAR | string]) + | (write-read-repeat REG [INT-OR-CHAR | string | ARRAY]?) + READ := (read REG) | (read REG REG) + | (read-if REG ARITH_OP ARG CCL_BLOCK CCL_BLOCK) + | (read-branch REG CCL_BLOCK [CCL_BLOCK ...]) + WRITE := (write REG) | (write REG REG) + | (write INT-OR-CHAR) | (write STRING) | STRING + | (write REG ARRAY) + END := (end) + + REG := r0 | r1 | r2 | r3 | r4 | r5 | r6 | r7 + ARG := REG | INT-OR-CHAR + OP := + | - | * | / | % | & | '|' | ^ | << | >> | <8 | >8 | // + | < | > | == | <= | >= | != + SELF_OP := + += | -= | *= | /= | %= | &= | '|=' | ^= | <<= | >>= + ARRAY := '[' INT-OR-CHAR ... ']' + INT-OR-CHAR := INT | CHAR + + MACHINE CODE: + + The machine code consists of a vector of 32-bit words. + The first such word specifies the start of the EOF section of the code; + this is the code executed to handle any stuff that needs to be done + (e.g. designating back to ASCII and left-to-right mode) after all + other encoded/decoded data has been written out. This is not used for + charset CCL programs. + + REGISTER: 0..7 -- referred by RRR or rrr + + OPERATOR BIT FIELD (27-bit): XXXXXXXXXXXXXXX RRR TTTTT + TTTTT (5-bit): operator type + RRR (3-bit): register number + XXXXXXXXXXXXXXXX (15-bit): + CCCCCCCCCCCCCCC: constant or address + 000000000000rrr: register number + + AAAA: 00000 + + 00001 - + 00010 * + 00011 / + 00100 % + 00101 & + 00110 | + 00111 ~ + + 01000 << + 01001 >> + 01010 <8 + 01011 >8 + 01100 // + 01101 not used + 01110 not used + 01111 not used + + 10000 < + 10001 > + 10010 == + 10011 <= + 10100 >= + 10101 != + + OPERATORS: TTTTT RRR XX.. + + SetCS: 00000 RRR C...C RRR = C...C + SetCL: 00001 RRR ..... RRR = c...c + c.............c + SetR: 00010 RRR ..rrr RRR = rrr + SetA: 00011 RRR ..rrr RRR = array[rrr] + C.............C size of array = C...C + c.............c contents = c...c + + Jump: 00100 000 c...c jump to c...c + JumpCond: 00101 RRR c...c if (!RRR) jump to c...c + WriteJump: 00110 RRR c...c Write1 RRR, jump to c...c + WriteReadJump: 00111 RRR c...c Write1, Read1 RRR, jump to c...c + WriteCJump: 01000 000 c...c Write1 C...C, jump to c...c + C...C + WriteCReadJump: 01001 RRR c...c Write1 C...C, Read1 RRR, + C.............C and jump to c...c + WriteSJump: 01010 000 c...c WriteS, jump to c...c + C.............C + S.............S + ... + WriteSReadJump: 01011 RRR c...c WriteS, Read1 RRR, jump to c...c + C.............C + S.............S + ... + WriteAReadJump: 01100 RRR c...c WriteA, Read1 RRR, jump to c...c + C.............C size of array = C...C + c.............c contents = c...c + ... + Branch: 01101 RRR C...C if (RRR >= 0 && RRR < C..) + c.............c branch to (RRR+1)th address + Read1: 01110 RRR ... read 1-byte to RRR + Read2: 01111 RRR ..rrr read 2-byte to RRR and rrr + ReadBranch: 10000 RRR C...C Read1 and Branch + c.............c + ... + Write1: 10001 RRR ..... write 1-byte RRR + Write2: 10010 RRR ..rrr write 2-byte RRR and rrr + WriteC: 10011 000 ..... write 1-char C...CC + C.............C + WriteS: 10100 000 ..... write C..-byte of string + C.............C + S.............S + ... + WriteA: 10101 RRR ..... write array[RRR] + C.............C size of array = C...C + c.............c contents = c...c + ... + End: 10110 000 ..... terminate the execution + + SetSelfCS: 10111 RRR C...C RRR AAAAA= C...C + ..........AAAAA + SetSelfCL: 11000 RRR ..... RRR AAAAA= c...c + c.............c + ..........AAAAA + SetSelfR: 11001 RRR ..Rrr RRR AAAAA= rrr + ..........AAAAA + SetExprCL: 11010 RRR ..Rrr RRR = rrr AAAAA c...c + c.............c + ..........AAAAA + SetExprR: 11011 RRR ..rrr RRR = rrr AAAAA Rrr + ............Rrr + ..........AAAAA + JumpCondC: 11100 RRR c...c if !(RRR AAAAA C..) jump to c...c + C.............C + ..........AAAAA + JumpCondR: 11101 RRR c...c if !(RRR AAAAA rrr) jump to c...c + ............rrr + ..........AAAAA + ReadJumpCondC: 11110 RRR c...c Read1 and JumpCondC + C.............C + ..........AAAAA + ReadJumpCondR: 11111 RRR c...c Read1 and JumpCondR + ............rrr + ..........AAAAA + + +File: internals.info, Node: The Lisp Reader and Compiler, Next: Lstreams, Prev: MULE Character Sets and Encodings, Up: Top + +18 The Lisp Reader and Compiler +******************************* + +Not yet documented. + + +File: internals.info, Node: Lstreams, Next: Consoles; Devices; Frames; Windows, Prev: The Lisp Reader and Compiler, Up: Top + +19 Lstreams +*********** + +An "lstream" is an internal Lisp object that provides a generic +buffering stream implementation. Conceptually, you send data to the +stream or read data from the stream, not caring what's on the other end +of the stream. The other end could be another stream, a file +descriptor, a stdio stream, a fixed block of memory, a reallocating +block of memory, etc. The main purpose of the stream is to provide a +standard interface and to do buffering. Macros are defined to read or +write characters, so the calling functions do not have to worry about +blocking data together in order to achieve efficiency. + +* Menu: + +* Creating an Lstream:: Creating an lstream object. +* Lstream Types:: Different sorts of things that are streamed. +* Lstream Functions:: Functions for working with lstreams. +* Lstream Methods:: Creating new lstream types. + + +File: internals.info, Node: Creating an Lstream, Next: Lstream Types, Up: Lstreams + +19.1 Creating an Lstream +======================== + +Lstreams come in different types, depending on what is being interfaced +to. Although the primitive for creating new lstreams is +`Lstream_new()', generally you do not call this directly. Instead, you +call some type-specific creation function, which creates the lstream +and initializes it as appropriate for the particular type. + + All lstream creation functions take a MODE argument, specifying what +mode the lstream should be opened as. This controls whether the +lstream is for input and output, and optionally whether data should be +blocked up in units of MULE characters. Note that some types of +lstreams can only be opened for input; others only for output; and +others can be opened either way. #### Richard Mlynarik thinks that +there should be a strict separation between input and output streams, +and he's probably right. + + MODE is a string, one of + +`"r"' + Open for reading. + +`"w"' + Open for writing. + +`"rc"' + Open for reading, but "read" never returns partial MULE characters. + +`"wc"' + Open for writing, but never writes partial MULE characters. + + +File: internals.info, Node: Lstream Types, Next: Lstream Functions, Prev: Creating an Lstream, Up: Lstreams + +19.2 Lstream Types +================== + +stdio + +filedesc + +lisp-string + +fixed-buffer + +resizing-buffer + +dynarr + +lisp-buffer + +print + +decoding + +encoding + + +File: internals.info, Node: Lstream Functions, Next: Lstream Methods, Prev: Lstream Types, Up: Lstreams + +19.3 Lstream Functions +====================== + + -- Function: Lstream * Lstream_new (Lstream_implementation *IMP, const + char *MODE) + Allocate and return a new Lstream. This function is not really + meant to be called directly; rather, each stream type should + provide its own stream creation function, which creates the stream + and does any other necessary creation stuff (e.g. opening a file). + + -- Function: void Lstream_set_buffering (Lstream *LSTR, + Lstream_buffering BUFFERING, int BUFFERING_SIZE) + Change the buffering of a stream. See `lstream.h'. By default the + buffering is `STREAM_BLOCK_BUFFERED'. + + -- Function: int Lstream_flush (Lstream *LSTR) + Flush out any pending unwritten data in the stream. Clear any + buffered input data. Returns 0 on success, -1 on error. + + -- Macro: int Lstream_putc (Lstream *STREAM, int C) + Write out one byte to the stream. This is a macro and so it is + very efficient. The C argument is only evaluated once but the + STREAM argument is evaluated more than once. Returns 0 on + success, -1 on error. + + -- Macro: int Lstream_getc (Lstream *STREAM) + Read one byte from the stream. This is a macro and so it is very + efficient. The STREAM argument is evaluated more than once. + Return value is -1 for EOF or error. + + -- Macro: void Lstream_ungetc (Lstream *STREAM, int C) + Push one byte back onto the input queue. This will be the next + byte read from the stream. Any number of bytes can be pushed back + and will be read in the reverse order they were pushed back--most + recent first. (This is necessary for consistency--if there are a + number of bytes that have been unread and I read and unread a + byte, it needs to be the first to be read again.) This is a macro + and so it is very efficient. The C argument is only evaluated + once but the STREAM argument is evaluated more than once. + + -- Function: int Lstream_fputc (Lstream *STREAM, int C) + -- Function: int Lstream_fgetc (Lstream *STREAM) + -- Function: void Lstream_fungetc (Lstream *STREAM, int C) + Function equivalents of the above macros. + + -- Function: ssize_t Lstream_read (Lstream *STREAM, void *DATA, size_t + SIZE) + Read SIZE bytes of DATA from the stream. Return the number of + bytes read. 0 means EOF. -1 means an error occurred and no bytes + were read. + + -- Function: ssize_t Lstream_write (Lstream *STREAM, void *DATA, + size_t SIZE) + Write SIZE bytes of DATA to the stream. Return the number of + bytes written. -1 means an error occurred and no bytes were + written. + + -- Function: void Lstream_unread (Lstream *STREAM, void *DATA, size_t + SIZE) + Push back SIZE bytes of DATA onto the input queue. The next call + to `Lstream_read()' with the same size will read the same bytes + back. Note that this will be the case even if there is other + pending unread data. + + -- Function: int Lstream_close (Lstream *STREAM) + Close the stream. All data will be flushed out. + + -- Function: void Lstream_reopen (Lstream *STREAM) + Reopen a closed stream. This enables I/O on it again. This is not + meant to be called except from a wrapper routine that reinitializes + variables and such--the close routine may well have freed some + necessary storage structures, for example. + + -- Function: void Lstream_rewind (Lstream *STREAM) + Rewind the stream to the beginning. + + +File: internals.info, Node: Lstream Methods, Prev: Lstream Functions, Up: Lstreams + +19.4 Lstream Methods +==================== + + -- Lstream Method: ssize_t reader (Lstream *STREAM, unsigned char + *DATA, size_t SIZE) + Read some data from the stream's end and store it into DATA, which + can hold SIZE bytes. Return the number of bytes read. A return + value of 0 means no bytes can be read at this time. This may be + because of an EOF, or because there is a granularity greater than + one byte that the stream imposes on the returned data, and SIZE is + less than this granularity. (This will happen frequently for + streams that need to return whole characters, because + `Lstream_read()' calls the reader function repeatedly until it has + the number of bytes it wants or until 0 is returned.) The lstream + functions do not treat a 0 return as EOF or do anything special; + however, the calling function will interpret any 0 it gets back as + EOF. This will normally not happen unless the caller calls + `Lstream_read()' with a very small size. + + This function can be `NULL' if the stream is output-only. + + -- Lstream Method: ssize_t writer (Lstream *STREAM, const unsigned + char *DATA, size_t SIZE) + Send some data to the stream's end. Data to be sent is in DATA + and is SIZE bytes. Return the number of bytes sent. This + function can send and return fewer bytes than is passed in; in that + case, the function will just be called again until there is no + data left or 0 is returned. A return value of 0 means that no + more data can be currently stored, but there is no error; the data + will be squirreled away until the writer can accept data. (This is + useful, e.g., if you're dealing with a non-blocking file + descriptor and are getting `EWOULDBLOCK' errors.) This function + can be `NULL' if the stream is input-only. + + -- Lstream Method: int rewinder (Lstream *STREAM) + Rewind the stream. If this is `NULL', the stream is not seekable. + + -- Lstream Method: int seekable_p (Lstream *STREAM) + Indicate whether this stream is seekable--i.e. it can be rewound. + This method is ignored if the stream does not have a rewind + method. If this method is not present, the result is determined + by whether a rewind method is present. + + -- Lstream Method: int flusher (Lstream *STREAM) + Perform any additional operations necessary to flush the data in + this stream. + + -- Lstream Method: int pseudo_closer (Lstream *STREAM) + + -- Lstream Method: int closer (Lstream *STREAM) + Perform any additional operations necessary to close this stream + down. May be `NULL'. This function is called when + `Lstream_close()' is called or when the stream is + garbage-collected. When this function is called, all pending data + in the stream will already have been written out. + + -- Lstream Method: Lisp_Object marker (Lisp_Object LSTREAM, void + (*MARKFUN) (Lisp_Object)) + Mark this object for garbage collection. Same semantics as a + standard `Lisp_Object' marker. This function can be `NULL'. + + +File: internals.info, Node: Consoles; Devices; Frames; Windows, Next: The Redisplay Mechanism, Prev: Lstreams, Up: Top + +20 Consoles; Devices; Frames; Windows +************************************* + +* Menu: + +* Introduction to Consoles; Devices; Frames; Windows:: +* Point:: +* Window Hierarchy:: +* The Window Object:: + + +File: internals.info, Node: Introduction to Consoles; Devices; Frames; Windows, Next: Point, Up: Consoles; Devices; Frames; Windows + +20.1 Introduction to Consoles; Devices; Frames; Windows +======================================================= + +A window-system window that you see on the screen is called a "frame" +in Emacs terminology. Each frame is subdivided into one or more +non-overlapping panes, called (confusingly) "windows". Each window +displays the text of a buffer in it. (See above on Buffers.) Note that +buffers and windows are independent entities: Two or more windows can +be displaying the same buffer (potentially in different locations), and +a buffer can be displayed in no windows. + + A single display screen that contains one or more frames is called a +"display". Under most circumstances, there is only one display. +However, more than one display can exist, for example if you have a +"multi-headed" console, i.e. one with a single keyboard but multiple +displays. (Typically in such a situation, the various displays act like +one large display, in that the mouse is only in one of them at a time, +and moving the mouse off of one moves it into another.) In some cases, +the different displays will have different characteristics, e.g. one +color and one mono. + + XEmacs can display frames on multiple displays. It can even deal +simultaneously with frames on multiple keyboards (called "consoles" in +XEmacs terminology). Here is one case where this might be useful: You +are using XEmacs on your workstation at work, and leave it running. +Then you go home and dial in on a TTY line, and you can use the +already-running XEmacs process to display another frame on your local +TTY. + + Thus, there is a hierarchy console -> display -> frame -> window. +There is a separate Lisp object type for each of these four concepts. +Furthermore, there is logically a "selected console", "selected +display", "selected frame", and "selected window". Each of these +objects is distinguished in various ways, such as being the default +object for various functions that act on objects of that type. Note +that every containing object remembers the "selected" object among the +objects that it contains: e.g. not only is there a selected window, but +every frame remembers the last window in it that was selected, and +changing the selected frame causes the remembered window within it to +become the selected window. Similar relationships apply for consoles +to devices and devices to frames. + + +File: internals.info, Node: Point, Next: Window Hierarchy, Prev: Introduction to Consoles; Devices; Frames; Windows, Up: Consoles; Devices; Frames; Windows + +20.2 Point +========== + +Recall that every buffer has a current insertion position, called +"point". Now, two or more windows may be displaying the same buffer, +and the text cursor in the two windows (i.e. `point') can be in two +different places. You may ask, how can that be, since each buffer has +only one value of `point'? The answer is that each window also has a +value of `point' that is squirreled away in it. There is only one +selected window, and the value of "point" in that buffer corresponds to +that window. When the selected window is changed from one window to +another displaying the same buffer, the old value of `point' is stored +into the old window's "point" and the value of `point' from the new +window is retrieved and made the value of `point' in the buffer. This +means that `window-point' for the selected window is potentially +inaccurate, and if you want to retrieve the correct value of `point' +for a window, you must special-case on the selected window and retrieve +the buffer's point instead. This is related to why +`save-window-excursion' does not save the selected window's value of +`point'. + + +File: internals.info, Node: Window Hierarchy, Next: The Window Object, Prev: Point, Up: Consoles; Devices; Frames; Windows + +20.3 Window Hierarchy +===================== + +If a frame contains multiple windows (panes), they are always created +by splitting an existing window along the horizontal or vertical axis. +Terminology is a bit confusing here: to "split a window horizontally" +means to create two side-by-side windows, i.e. to make a _vertical_ cut +in a window. Likewise, to "split a window vertically" means to create +two windows, one above the other, by making a _horizontal_ cut. + + If you split a window and then split again along the same axis, you +will end up with a number of panes all arranged along the same axis. +The precise way in which the splits were made should not be important, +and this is reflected internally. Internally, all windows are arranged +in a tree, consisting of two types of windows, "combination" windows +(which have children, and are covered completely by those children) and +"leaf" windows, which have no children and are visible. Every +combination window has two or more children, all arranged along the same +axis. There are (logically) two subtypes of windows, depending on +whether their children are horizontally or vertically arrayed. There is +always one root window, which is either a leaf window (if the frame +contains only one window) or a combination window (if the frame contains +more than one window). In the latter case, the root window will have +two or more children, either horizontally or vertically arrayed, and +each of those children will be either a leaf window or another +combination window. + + Here are some rules: + + 1. Horizontal combination windows can never have children that are + horizontal combination windows; same for vertical. + + 2. Only leaf windows can be split (obviously) and this splitting does + one of two things: (a) turns the leaf window into a combination + window and creates two new leaf children, or (b) turns the leaf + window into one of the two new leaves and creates the other leaf. + Rule (1) dictates which of these two outcomes happens. + + 3. Every combination window must have at least two children. + + 4. Leaf windows can never become combination windows. They can be + deleted, however. If this results in a violation of (3), the + parent combination window also gets deleted. + + 5. All functions that accept windows must be prepared to accept + combination windows, and do something sane (e.g. signal an error + if so). Combination windows _do_ escape to the Lisp level. + + 6. All windows have three fields governing their contents: these are + "hchild" (a list of horizontally-arrayed children), "vchild" (a + list of vertically-arrayed children), and "buffer" (the buffer + contained in a leaf window). Exactly one of these will be + non-`nil'. Remember that "horizontally-arrayed" means + "side-by-side" and "vertically-arrayed" means "one above the + other". + + 7. Leaf windows also have markers in their `start' (the first buffer + position displayed in the window) and `pointm' (the window's + stashed value of `point'--see above) fields, while combination + windows have `nil' in these fields. + + 8. The list of children for a window is threaded through the `next' + and `prev' fields of each child window. + + 9. *Deleted windows can be undeleted*. This happens as a result of + restoring a window configuration, and is unlike frames, displays, + and consoles, which, once deleted, can never be restored. + Deleting a window does nothing except set a special `dead' bit to + 1 and clear out the `next', `prev', `hchild', and `vchild' fields, + for GC purposes. + + 10. Most frames actually have two top-level windows--one for the + minibuffer and one (the "root") for everything else. The modeline + (if present) separates these two. The `next' field of the root + points to the minibuffer, and the `prev' field of the minibuffer + points to the root. The other `next' and `prev' fields are `nil', + and the frame points to both of these windows. Minibuffer-less + frames have no minibuffer window, and the `next' and `prev' of the + root window are `nil'. Minibuffer-only frames have no root + window, and the `next' of the minibuffer window is `nil' but the + `prev' points to itself. (#### This is an artifact that should be + fixed.) + + +File: internals.info, Node: The Window Object, Prev: Window Hierarchy, Up: Consoles; Devices; Frames; Windows + +20.4 The Window Object +====================== + +Windows have the following accessible fields: + +`frame' + The frame that this window is on. + +`mini_p' + Non-`nil' if this window is a minibuffer window. + +`buffer' + The buffer that the window is displaying. This may change often + during the life of the window. + +`dedicated' + Non-`nil' if this window is dedicated to its buffer. + +`pointm' + This is the value of point in the current buffer when this window + is selected; when it is not selected, it retains its previous + value. + +`start' + The position in the buffer that is the first character to be + displayed in the window. + +`force_start' + If this flag is non-`nil', it says that the window has been + scrolled explicitly by the Lisp program. This affects what the + next redisplay does if point is off the screen: instead of + scrolling the window to show the text around point, it moves point + to a location that is on the screen. + +`last_modified' + The `modified' field of the window's buffer, as of the last time a + redisplay completed in this window. + +`last_point' + The buffer's value of point, as of the last time a redisplay + completed in this window. + +`left' + This is the left-hand edge of the window, measured in columns. + (The leftmost column on the screen is column 0.) + +`top' + This is the top edge of the window, measured in lines. (The top + line on the screen is line 0.) + +`height' + The height of the window, measured in lines. + +`width' + The width of the window, measured in columns. + +`next' + This is the window that is the next in the chain of siblings. It + is `nil' in a window that is the rightmost or bottommost of a + group of siblings. + +`prev' + This is the window that is the previous in the chain of siblings. + It is `nil' in a window that is the leftmost or topmost of a group + of siblings. + +`parent' + Internally, XEmacs arranges windows in a tree; each group of + siblings has a parent window whose area includes all the siblings. + This field points to a window's parent. + + Parent windows do not display buffers, and play little role in + display except to shape their child windows. Emacs Lisp programs + usually have no access to the parent windows; they operate on the + windows at the leaves of the tree, which actually display buffers. + +`hscroll' + This is the number of columns that the display in the window is + scrolled horizontally to the left. Normally, this is 0. + +`use_time' + This is the last time that the window was selected. The function + `get-lru-window' uses this field. + +`display_table' + The window's display table, or `nil' if none is specified for it. + +`update_mode_line' + Non-`nil' means this window's mode line needs to be updated. + +`base_line_number' + The line number of a certain position in the buffer, or `nil'. + This is used for displaying the line number of point in the mode + line. + +`base_line_pos' + The position in the buffer for which the line number is known, or + `nil' meaning none is known. + +`region_showing' + If the region (or part of it) is highlighted in this window, this + field holds the mark position that made one end of that region. + Otherwise, this field is `nil'. + + +File: internals.info, Node: The Redisplay Mechanism, Next: Extents, Prev: Consoles; Devices; Frames; Windows, Up: Top + +21 The Redisplay Mechanism +************************** + +The redisplay mechanism is one of the most complicated sections of +XEmacs, especially from a conceptual standpoint. This is doubly so +because, unlike for the basic aspects of the Lisp interpreter, the +computer science theories of how to efficiently handle redisplay are not +well-developed. + + When working with the redisplay mechanism, remember the Golden Rules +of Redisplay: + + 1. It Is Better To Be Correct Than Fast. + + 2. Thou Shalt Not Run Elisp From Within Redisplay. + + 3. It Is Better To Be Fast Than Not To Be. + +* Menu: + +* Critical Redisplay Sections:: +* Line Start Cache:: +* Redisplay Piece by Piece:: + + +File: internals.info, Node: Critical Redisplay Sections, Next: Line Start Cache, Up: The Redisplay Mechanism + +21.1 Critical Redisplay Sections +================================ + +Within this section, we are defenseless and assume that the following +cannot happen: + + 1. garbage collection + + 2. Lisp code evaluation + + 3. frame size changes + + We ensure (3) by calling `hold_frame_size_changes()', which will +cause any pending frame size changes to get put on hold till after the +end of the critical section. (1) follows automatically if (2) is met. +#### Unfortunately, there are some places where Lisp code can be called +within this section. We need to remove them. + + If `Fsignal()' is called during this critical section, we will +`abort()'. + + If garbage collection is called during this critical section, we +simply return. #### We should abort instead. + + #### If a frame-size change does occur we should probably actually +be preempting redisplay. + + +File: internals.info, Node: Line Start Cache, Next: Redisplay Piece by Piece, Prev: Critical Redisplay Sections, Up: The Redisplay Mechanism + +21.2 Line Start Cache +===================== + +The traditional scrolling code in Emacs breaks in a variable height +world. It depends on the key assumption that the number of lines that +can be displayed at any given time is fixed. This led to a complete +separation of the scrolling code from the redisplay code. In order to +fully support variable height lines, the scrolling code must actually be +tightly integrated with redisplay. Only redisplay can determine how +many lines will be displayed on a screen for any given starting point. + + What is ideally wanted is a complete list of the starting buffer +position for every possible display line of a buffer along with the +height of that display line. Maintaining such a full list would be very +expensive. We settle for having it include information for all areas +which we happen to generate anyhow (i.e. the region currently being +displayed) and for those areas we need to work with. + + In order to ensure that the cache accurately represents what +redisplay would actually show, it is necessary to invalidate it in many +situations. If the buffer changes, the starting positions may no longer +be correct. If a face or an extent has changed then the line heights +may have altered. These events happen frequently enough that the cache +can end up being constantly disabled. With this potentially constant +invalidation when is the cache ever useful? + + Even if the cache is invalidated before every single usage, it is +necessary. Scrolling often requires knowledge about display lines which +are actually above or below the visible region. The cache provides a +convenient light-weight method of storing this information for multiple +display regions. This knowledge is necessary for the scrolling code to +always obey the First Golden Rule of Redisplay. + + If the cache already contains all of the information that the +scrolling routines happen to need so that it doesn't have to go +generate it, then we are able to obey the Third Golden Rule of +Redisplay. The first thing we do to help out the cache is to always +add the displayed region. This region had to be generated anyway, so +the cache ends up getting the information basically for free. In those +cases where a user is simply scrolling around viewing a buffer there is +a high probability that this is sufficient to always provide the needed +information. The second thing we can do is be smart about invalidating +the cache. + + TODO--Be smart about invalidating the cache. Potential places: + + * Insertions at end-of-line which don't cause line-wraps do not + alter the starting positions of any display lines. These types of + buffer modifications should not invalidate the cache. This is + actually a large optimization for redisplay speed as well. + + * Buffer modifications frequently only affect the display of lines + at and below where they occur. In these situations we should only + invalidate the part of the cache starting at where the + modification occurs. + + In case you're wondering, the Second Golden Rule of Redisplay is not +applicable. + + +File: internals.info, Node: Redisplay Piece by Piece, Prev: Line Start Cache, Up: The Redisplay Mechanism + +21.3 Redisplay Piece by Piece +============================= + +As you can begin to see redisplay is complex and also not well +documented. Chuck no longer works on XEmacs so this section is my take +on the workings of redisplay. + + Redisplay happens in three phases: + + 1. Determine desired display in area that needs redisplay. + Implemented by `redisplay.c' + + 2. Compare desired display with current display Implemented by + `redisplay-output.c' + + 3. Output changes Implemented by `redisplay-output.c', + `redisplay-x.c', `redisplay-msw.c' and `redisplay-tty.c' + + Steps 1 and 2 are device-independent and relatively complex. Step 3 +is mostly device-dependent. + + Determining the desired display + + Display attributes are stored in `display_line' structures. Each +`display_line' consists of a set of `display_block''s and each +`display_block' contains a number of `rune''s. Generally dynarr's of +`display_line''s are held by each window representing the current +display and the desired display. + + The `display_line' structures are tightly tied to buffers which +presents a problem for redisplay as this connection is bogus for the +modeline. Hence the `display_line' generation routines are duplicated +for generating the modeline. This means that the modeline display code +has many bugs that the standard redisplay code does not. + + The guts of `display_line' generation are in `create_text_block', +which creates a single display line for the desired locale. This +incrementally parses the characters on the current line and generates +redisplay structures for each. + + Gutter redisplay is different. Because the data to display is stored +in a string we cannot use `create_text_block'. Instead we use +`create_text_string_block' which performs the same function as +`create_text_block' but for strings. Many of the complexities of +`create_text_block' to do with cursor handling and selective display +have been removed. + + +File: internals.info, Node: Extents, Next: Faces, Prev: The Redisplay Mechanism, Up: Top + +22 Extents +********** + +* Menu: + +* Introduction to Extents:: Extents are ranges over text, with properties. +* Extent Ordering:: How extents are ordered internally. +* Format of the Extent Info:: The extent information in a buffer or string. +* Zero-Length Extents:: A weird special case. +* Mathematics of Extent Ordering:: A rigorous foundation. +* Extent Fragments:: Cached information useful for redisplay. + + +File: internals.info, Node: Introduction to Extents, Next: Extent Ordering, Up: Extents + +22.1 Introduction to Extents +============================ + +Extents are regions over a buffer, with a start and an end position +denoting the region of the buffer included in the extent. In addition, +either end can be closed or open, meaning that the endpoint is or is +not logically included in the extent. Insertion of a character at a +closed endpoint causes the character to go inside the extent; insertion +at an open endpoint causes the character to go outside. + + Extent endpoints are stored using memory indices (see `insdel.c'), +to minimize the amount of adjusting that needs to be done when +characters are inserted or deleted. + + (Formerly, extent endpoints at the gap could be either before or +after the gap, depending on the open/closedness of the endpoint. The +intent of this was to make it so that insertions would automatically go +inside or out of extents as necessary with no further work needing to +be done. It didn't work out that way, however, and just ended up +complexifying and buggifying all the rest of the code.) + + +File: internals.info, Node: Extent Ordering, Next: Format of the Extent Info, Prev: Introduction to Extents, Up: Extents + +22.2 Extent Ordering +==================== + +Extents are compared using memory indices. There are two orderings for +extents and both orders are kept current at all times. The normal or +"display" order is as follows: + + Extent A is ``less than'' extent B, + that is, earlier in the display order, + if: A-start < B-start, + or if: A-start = B-start, and A-end > B-end + + So if two extents begin at the same position, the larger of them is +the earlier one in the display order (`EXTENT_LESS' is true). + + For the e-order, the same thing holds: + + Extent A is ``less than'' extent B in e-order, + that is, later in the buffer, + if: A-end < B-end, + or if: A-end = B-end, and A-start > B-start + + So if two extents end at the same position, the smaller of them is +the earlier one in the e-order (`EXTENT_E_LESS' is true). + + The display order and the e-order are complementary orders: any +theorem about the display order also applies to the e-order if you swap +all occurrences of "display order" and "e-order", "less than" and +"greater than", and "extent start" and "extent end". + + +File: internals.info, Node: Format of the Extent Info, Next: Zero-Length Extents, Prev: Extent Ordering, Up: Extents + +22.3 Format of the Extent Info +============================== + +An extent-info structure consists of a list of the buffer or string's +extents and a "stack of extents" that lists all of the extents over a +particular position. The stack-of-extents info is used for +optimization purposes--it basically caches some info that might be +expensive to compute. Certain otherwise hard computations are easy +given the stack of extents over a particular position, and if the stack +of extents over a nearby position is known (because it was calculated +at some prior point in time), it's easy to move the stack of extents to +the proper position. + + Given that the stack of extents is an optimization, and given that +it requires memory, a string's stack of extents is wiped out each time +a garbage collection occurs. Therefore, any time you retrieve the +stack of extents, it might not be there. If you need it to be there, +use the `_force' version. + + Similarly, a string may or may not have an extent_info structure. +(Generally it won't if there haven't been any extents added to the +string.) So use the `_force' version if you need the extent_info +structure to be there. + + A list of extents is maintained as a double gap array: one gap array +is ordered by start index (the "display order") and the other is +ordered by end index (the "e-order"). Note that positions in an extent +list should logically be conceived of as referring _to_ a particular +extent (as is the norm in programs) rather than sitting between two +extents. Note also that callers of these functions should not be aware +of the fact that the extent list is implemented as an array, except for +the fact that positions are integers (this should be generalized to +handle integers and linked list equally well). + + +File: internals.info, Node: Zero-Length Extents, Next: Mathematics of Extent Ordering, Prev: Format of the Extent Info, Up: Extents + +22.4 Zero-Length Extents +======================== + +Extents can be zero-length, and will end up that way if their endpoints +are explicitly set that way or if their detachable property is `nil' +and all the text in the extent is deleted. (The exception is open-open +zero-length extents, which are barred from existing because there is no +sensible way to define their properties. Deletion of the text in an +open-open extent causes it to be converted into a closed-open extent.) +Zero-length extents are primarily used to represent annotations, and +behave as follows: + + 1. Insertion at the position of a zero-length extent expands the + extent if both endpoints are closed; goes after the extent if it + is closed-open; and goes before the extent if it is open-closed. + + 2. Deletion of a character on a side of a zero-length extent whose + corresponding endpoint is closed causes the extent to be detached + if it is detachable; if the extent is not detachable or the + corresponding endpoint is open, the extent remains in the buffer, + moving as necessary. + + Note that closed-open, non-detachable zero-length extents behave +exactly like markers and that open-closed, non-detachable zero-length +extents behave like the "point-type" marker in Mule. + + +File: internals.info, Node: Mathematics of Extent Ordering, Next: Extent Fragments, Prev: Zero-Length Extents, Up: Extents + +22.5 Mathematics of Extent Ordering +=================================== + +The extents in a buffer are ordered by "display order" because that is +that order that the redisplay mechanism needs to process them in. The +e-order is an auxiliary ordering used to facilitate operations over +extents. The operations that can be performed on the ordered list of +extents in a buffer are + + 1. Locate where an extent would go if inserted into the list. + + 2. Insert an extent into the list. + + 3. Remove an extent from the list. + + 4. Map over all the extents that overlap a range. + + (4) requires being able to determine the first and last extents that +overlap a range. + + NOTE: "overlap" is used as follows: + + * two ranges overlap if they have at least one point in common. + Whether the endpoints are open or closed makes a difference here. + + * a point overlaps a range if the point is contained within the + range; this is equivalent to treating a point P as the range [P, + P]. + + * In the case of an _extent_ overlapping a point or range, the extent + is normally treated as having closed endpoints. This applies + consistently in the discussion of stacks of extents and such below. + Note that this definition of overlap is not necessarily consistent + with the extents that `map-extents' maps over, since `map-extents' + sometimes pays attention to whether the endpoints of an extents + are open or closed. But for our purposes, it greatly simplifies + things to treat all extents as having closed endpoints. + + First, define >, <, <=, etc. as applied to extents to mean +comparison according to the display order. Comparison between an +extent E and an index I means comparison between E and the range [I, I]. + + Also define e>, e<, e<=, etc. to mean comparison according to the +e-order. + + For any range R, define R(0) to be the starting index of the range +and R(1) to be the ending index of the range. + + For any extent E, define E(next) to be the extent directly following +E, and E(prev) to be the extent directly preceding E. Assume E(next) +and E(prev) can be determined from E in constant time. (This is +because we store the extent list as a doubly linked list.) + + Similarly, define E(e-next) and E(e-prev) to be the extents directly +following and preceding E in the e-order. + + Now: + + Let R be a range. Let F be the first extent overlapping R. Let L +be the last extent overlapping R. + + Theorem 1: R(1) lies between L and L(next), i.e. L <= R(1) < L(next). + + This follows easily from the definition of display order. The basic +reason that this theorem applies is that the display order sorts by +increasing starting index. + + Therefore, we can determine L just by looking at where we would +insert R(1) into the list, and if we know F and are moving forward over +extents, we can easily determine when we've hit L by comparing the +extent we're at to R(1). + + Theorem 2: F(e-prev) e< [1, R(0)] e<= F. + + This is the analog of Theorem 1, and applies because the e-order +sorts by increasing ending index. + + Therefore, F can be found in the same amount of time as operation +(1), i.e. the time that it takes to locate where an extent would go if +inserted into the e-order list. + + If the lists were stored as balanced binary trees, then operation (1) +would take logarithmic time, which is usually quite fast. However, +currently they're stored as simple doubly-linked lists, and instead we +do some caching to try to speed things up. + + Define a "stack of extents" (or "SOE") as the set of extents +(ordered in the display order) that overlap an index I, together with +the SOE's "previous" extent, which is an extent that precedes I in the +e-order. (Hopefully there will not be very many extents between I and +the previous extent.) + + Now: + + Let I be an index, let S be the stack of extents on I, let F be the +first extent in S, and let P be S's previous extent. + + Theorem 3: The first extent in S is the first extent that overlaps +any range [I, J]. + + Proof: Any extent that overlaps [I, J] but does not include I must +have a start index > I, and thus be greater than any extent in S. + + Therefore, finding the first extent that overlaps a range R is the +same as finding the first extent that overlaps R(0). + + Theorem 4: Let I2 be an index such that I2 > I, and let F2 be the +first extent that overlaps I2. Then, either F2 is in S or F2 is +greater than any extent in S. + + Proof: If F2 does not include I then its start index is greater than +I and thus it is greater than any extent in S, including F. Otherwise, +F2 includes I and thus is in S, and thus F2 >= F. + + +File: internals.info, Node: Extent Fragments, Prev: Mathematics of Extent Ordering, Up: Extents + +22.6 Extent Fragments +===================== + +Imagine that the buffer is divided up into contiguous, non-overlapping +"runs" of text such that no extent starts or ends within a run (extents +that abut the run don't count). + + An extent fragment is a structure that holds data about the run that +contains a particular buffer position (if the buffer position is at the +junction of two runs, the run after the position is used)--the +beginning and end of the run, a list of all of the extents in that run, +the "merged face" that results from merging all of the faces +corresponding to those extents, the begin and end glyphs at the +beginning of the run, etc. This is the information that redisplay needs +in order to display this run. + + Extent fragments have to be very quick to update to a new buffer +position when moving linearly through the buffer. They rely on the +stack-of-extents code, which does the heavy-duty algorithmic work of +determining which extents overly a particular position. + + +File: internals.info, Node: Faces, Next: Glyphs, Prev: Extents, Up: Top + +23 Faces +******** + +Not yet documented. + + +File: internals.info, Node: Glyphs, Next: Specifiers, Prev: Faces, Up: Top + +24 Glyphs +********* + +Glyphs are graphical elements that can be displayed in XEmacs buffers or +gutters. We use the term graphical element here in the broadest possible +sense since glyphs can be as mundane as text or as arcane as a native +tab widget. + + In XEmacs, glyphs represent the uninstantiated state of graphical +elements, i.e. they hold all the information necessary to produce an +image on-screen but the image need not exist at this stage, and multiple +screen images can be instantiated from a single glyph. + + Glyphs are lazily instantiated by calling one of the glyph +functions. This usually occurs within redisplay when `Fglyph_height' is +called. Instantiation causes an image-instance to be created and +cached. This cache is on a per-device basis for all glyphs except +widget-glyphs, and on a per-window basis for widgets-glyphs. The +caching is done by `image_instantiate' and is necessary because it is +generally possible to display an image-instance in multiple domains. +For instance if we create a Pixmap, we can actually display this on +multiple windows - even though we only need a single Pixmap instance to +do this. If caching wasn't done then it would be necessary to create +image-instances for every displayable occurrence of a glyph - and every +usage - and this would be extremely memory and cpu intensive. + + Widget-glyphs (a.k.a native widgets) are not cached in this way. +This is because widget-glyph image-instances on screen are toolkit +windows, and thus cannot be reused in multiple XEmacs domains. Thus +widget-glyphs are cached on an XEmacs window basis. + + Any action on a glyph first consults the cache before actually +instantiating a widget. + +24.1 Glyph Instantiation +======================== + +Glyph instantiation is a hairy topic and requires some explanation. The +guts of glyph instantiation is contained within `image_instantiate'. A +glyph contains an image which is a specifier. When a glyph function - +for instance `Fglyph_height' - asks for a property of the glyph that +can only be determined from its instantiated state, then the glyph +image is instantiated and an image instance created. The instantiation +process is governed by the specifier code and goes through a series of +steps: + + * Validation. Instantiation of image instances happens dynamically - + often within the guts of redisplay. Thus it is often not feasible + to catch instantiator errors at instantiation time. Instead the + instantiator is validated at the time it is added to the image + specifier. This function is defined by `image_validate' and at a + simple level validates keyword value pairs. + + * Duplication. The specifier code by default takes a copy of the + instantiator. This is reasonable for most specifiers but in the + case of widget-glyphs can be problematic, since some of the + properties in the instantiator - for instance callbacks - could + cause infinite recursion in the copying process. Thus the image + code defines a function - `image_copy_instantiator' - which will + selectively copy values. This is controlled by the way that a + keyword is defined either using `IIFORMAT_VALID_KEYWORD' or + `IIFORMAT_VALID_NONCOPY_KEYWORD'. Note that the image caching and + redisplay code relies on instantiator copying to ensure that + current and new instantiators are actually different rather than + referring to the same thing. + + * Normalization. Once the instantiator has been copied it must be + converted into a form that is viable at instantiation time. This + can involve no changes at all, but typically involves things like + converting file names to the actual data. This function is defined + by `image_going_to_add' and `normalize_image_instantiator'. + + * Instantiation. When an image instance is actually required for + display it is instantiated using `image_instantiate'. This + involves calling instantiate methods that are specific to the type + of image being instantiated. + + The final instantiation phase also involves a number of steps. In +order to understand these we need to describe a number of concepts. + + An image is instantiated in a "domain", where a domain can be any +one of a device, frame, window or image-instance. The domain gives the +image-instance context and identity and properties that affect the +appearance of the image-instance may be different for the same glyph +instantiated in different domains. An example is the face used to +display the image-instance. + + Although an image is instantiated in a particular domain the +instantiation domain is not necessarily the domain in which the +image-instance is cached. For example a pixmap can be instantiated in a +window be actually be cached on a per-device basis. The domain in which +the image-instance is actually cached is called the "governing-domain". +A governing-domain is currently either a device or a window. +Widget-glyphs and text-glyphs have a window as a governing-domain, all +other image-instances have a device as the governing-domain. The +governing domain for an image-instance is determined using the +governing_domain image-instance method. + +24.2 Widget-Glyphs +================== + +24.3 Widget-Glyphs in the MS-Windows Environment +================================================ + +To Do + +24.4 Widget-Glyphs in the X Environment +======================================= + +Widget-glyphs under X make heavy use of lwlib (*note Lucid Widget +Library::) for manipulating the native toolkit objects. This is +primarily so that different toolkits can be supported for +widget-glyphs, just as they are supported for features such as menubars +etc. + + Lwlib is extremely poorly documented and quite hairy so here is my +understanding of what goes on. + + Lwlib maintains a set of widget_instances which mirror the +hierarchical state of Xt widgets. I think this is so that widgets can +be updated and manipulated generically by the lwlib library. For +instance update_one_widget_instance can cope with multiple types of +widget and multiple types of toolkit. Each element in the widget +hierarchy is updated from its corresponding widget_instance by walking +the widget_instance tree recursively. + + This has desirable properties such as lw_modify_all_widgets which is +called from `glyphs-x.c' and updates all the properties of a widget +without having to know what the widget is or what toolkit it is from. +Unfortunately this also has hairy properties such as making the lwlib +code quite complex. And of course lwlib has to know at some level what +the widget is and how to set its properties. + + +File: internals.info, Node: Specifiers, Next: Menus, Prev: Glyphs, Up: Top + +25 Specifiers +************* + +Not yet documented. + + +File: internals.info, Node: Menus, Next: Subprocesses, Prev: Specifiers, Up: Top + +26 Menus +******** + +A menu is set by setting the value of the variable `current-menubar' +(which may be buffer-local) and then calling `set-menubar-dirty-flag' +to signal a change. This will cause the menu to be redrawn at the next +redisplay. The format of the data in `current-menubar' is described in +`menubar.c'. + + Internally the data in current-menubar is parsed into a tree of +`widget_value's' (defined in `lwlib.h'); this is accomplished by the +recursive function `menu_item_descriptor_to_widget_value()', called by +`compute_menubar_data()'. Such a tree is deallocated using +`free_widget_value()'. + + `update_screen_menubars()' is one of the external entry points. +This checks to see, for each screen, if that screen's menubar needs to +be updated. This is the case if + + 1. `set-menubar-dirty-flag' was called since the last redisplay. + (This function sets the C variable menubar_has_changed.) + + 2. The buffer displayed in the screen has changed. + + 3. The screen has no menubar currently displayed. + + `set_screen_menubar()' is called for each such screen. This +function calls `compute_menubar_data()' to create the tree of +widget_value's, then calls `lw_create_widget()', +`lw_modify_all_widgets()', and/or `lw_destroy_all_widgets()' to create +the X-Toolkit widget associated with the menu. + + `update_psheets()', the other external entry point, actually changes +the menus being displayed. It uses the widgets fixed by +`update_screen_menubars()' and calls various X functions to ensure that +the menus are displayed properly. + + The menubar widget is set up so that `pre_activate_callback()' is +called when the menu is first selected (i.e. mouse button goes down), +and `menubar_selection_callback()' is called when an item is selected. +`pre_activate_callback()' calls the function in activate-menubar-hook, +which can change the menubar (this is described in `menubar.c'). If +the menubar is changed, `set_screen_menubars()' is called. +`menubar_selection_callback()' enqueues a menu event, putting in it a +function to call (either `eval' or `call-interactively') and its +argument, which is the callback function or form given in the menu's +description. + + +File: internals.info, Node: Subprocesses, Next: Interface to the X Window System, Prev: Menus, Up: Top + +27 Subprocesses +*************** + +The fields of a process are: + +`name' + A string, the name of the process. + +`command' + A list containing the command arguments that were used to start + this process. + +`filter' + A function used to accept output from the process instead of a + buffer, or `nil'. + +`sentinel' + A function called whenever the process receives a signal, or `nil'. + +`buffer' + The associated buffer of the process. + +`pid' + An integer, the Unix process ID. + +`childp' + A flag, non-`nil' if this is really a child process. It is `nil' + for a network connection. + +`mark' + A marker indicating the position of the end of the last output + from this process inserted into the buffer. This is often but not + always the end of the buffer. + +`kill_without_query' + If this is non-`nil', killing XEmacs while this process is still + running does not ask for confirmation about killing the process. + +`raw_status_low' +`raw_status_high' + These two fields record 16 bits each of the process status + returned by the `wait' system call. + +`status' + The process status, as `process-status' should return it. + +`tick' +`update_tick' + If these two fields are not equal, a change in the status of the + process needs to be reported, either by running the sentinel or by + inserting a message in the process buffer. + +`pty_flag' + Non-`nil' if communication with the subprocess uses a PTY; `nil' + if it uses a pipe. + +`infd' + The file descriptor for input from the process. + +`outfd' + The file descriptor for output to the process. + +`subtty' + The file descriptor for the terminal that the subprocess is using. + (On some systems, there is no need to record this, so the value is + `-1'.) + +`tty_name' + The name of the terminal that the subprocess is using, or `nil' if + it is using pipes. + + +File: internals.info, Node: Interface to the X Window System, Next: Index, Prev: Subprocesses, Up: Top + +28 Interface to the X Window System +*********************************** + +Mostly undocumented. + +* Menu: + +* Lucid Widget Library:: An interface to various widget sets. + + +File: internals.info, Node: Lucid Widget Library, Up: Interface to the X Window System + +28.1 Lucid Widget Library +========================= + +Lwlib is extremely poorly documented and quite hairy. The author(s) +blame that on X, Xt, and Motif, with some justice, but also sufficient +hypocrisy to avoid drawing the obvious conclusion about their own work. + + The Lucid Widget Library is composed of two more or less independent +pieces. The first, as the name suggests, is a set of widgets. These +widgets are intended to resemble and improve on widgets provided in the +Motif toolkit but not in the Athena widgets, including menubars and +scrollbars. Recent additions by Andy Piper integrate some "modern" +widgets by Edward Falk, including checkboxes, radio buttons, progress +gauges, and index tab controls (aka notebooks). + + The second piece of the Lucid widget library is a generic interface +to several toolkits for X (including Xt, the Athena widget set, and +Motif, as well as the Lucid widgets themselves) so that core XEmacs +code need not know which widget set has been used to build the +graphical user interface. + +* Menu: + +* Generic Widget Interface:: The lwlib generic widget interface. +* Scrollbars:: +* Menubars:: +* Checkboxes and Radio Buttons:: +* Progress Bars:: +* Tab Controls:: + + +File: internals.info, Node: Generic Widget Interface, Next: Scrollbars, Up: Lucid Widget Library + +28.1.1 Generic Widget Interface +------------------------------- + +In general in any toolkit a widget may be a composite object. In Xt, +all widgets have an X window that they manage, but typically a complex +widget will have widget children, each of which manages a subwindow of +the parent widget's X window. These children may themselves be +composite widgets. Thus a widget is actually a tree or hierarchy of +widgets. + + For each toolkit widget, lwlib maintains a tree of `widget_values' +which mirror the hierarchical state of Xt widgets (including Motif, +Athena, 3D Athena, and Falk's widget sets). Each `widget_value' has +`contents' member, which points to the head of a linked list of its +children. The linked list of siblings is chained through the `next' +member of `widget_value'. + + +-----------+ + | composite | + +-----------+ + | + | contents + V + +-------+ next +-------+ next +-------+ + | child |----->| child |----->| child | + +-------+ +-------+ +-------+ + | + | contents + V + +-------------+ next +-------------+ + | grand child |----->| grand child | + +-------------+ +-------------+ + + The `widget_value' hierarchy of a composite widget with two simple + children and one composite child. + + The `widget_instance' structure maintains the inverse view of the +tree. As for the `widget_value', siblings are chained through the +`next' member. However, rather than naming children, the +`widget_instance' tree links to parents. + + +-----------+ + | composite | + +-----------+ + A + | parent + | + +-------+ next +-------+ next +-------+ + | child |----->| child |----->| child | + +-------+ +-------+ +-------+ + A + | parent + | + +-------------+ next +-------------+ + | grand child |----->| grand child | + +-------------+ +-------------+ + + The `widget_value' hierarchy of a composite widget with two simple + children and one composite child. + + This permits widgets derived from different toolkits to be updated +and manipulated generically by the lwlib library. For instance +`update_one_widget_instance' can cope with multiple types of widget and +multiple types of toolkit. Each element in the widget hierarchy is +updated from its corresponding `widget_value' by walking the +`widget_value' tree. This has desirable properties. For example, +`lw_modify_all_widgets' is called from `glyphs-x.c' and updates all the +properties of a widget without having to know what the widget is or +what toolkit it is from. Unfortunately this also has its hairy +properties; the lwlib code quite complex. And of course lwlib has to +know at some level what the widget is and how to set its properties. + + The `widget_instance' structure also contains a pointer to the root +of its tree. Widget instances are further confi + + +File: internals.info, Node: Scrollbars, Next: Menubars, Prev: Generic Widget Interface, Up: Lucid Widget Library + +28.1.2 Scrollbars +----------------- + + +File: internals.info, Node: Menubars, Next: Checkboxes and Radio Buttons, Prev: Scrollbars, Up: Lucid Widget Library + +28.1.3 Menubars +--------------- + + +File: internals.info, Node: Checkboxes and Radio Buttons, Next: Progress Bars, Prev: Menubars, Up: Lucid Widget Library + +28.1.4 Checkboxes and Radio Buttons +----------------------------------- + + +File: internals.info, Node: Progress Bars, Next: Tab Controls, Prev: Checkboxes and Radio Buttons, Up: Lucid Widget Library + +28.1.5 Progress Bars +-------------------- + + +File: internals.info, Node: Tab Controls, Prev: Progress Bars, Up: Lucid Widget Library + +28.1.6 Tab Controls +------------------- + + +File: internals.info, Node: Index, Prev: Interface to the X Window System, Up: Top + +Index +***** + +[index] +* Menu: + +* allocation from frob blocks: Allocation from Frob Blocks. + (line 6) +* allocation of objects in XEmacs Lisp: Allocation of Objects in XEmacs Lisp. + (line 6) +* allocation, introduction to: Introduction to Allocation. + (line 6) +* allocation, low-level: Low-level allocation. + (line 6) +* Amdahl Corporation: XEmacs. (line 6) +* Andreessen, Marc: XEmacs. (line 6) +* asynchronous subprocesses: Modules for Interfacing with the Operating System. + (line 18) +* bars, progress: Progress Bars. (line 6) +* Baur, Steve: XEmacs. (line 6) +* Benson, Eric: Lucid Emacs. (line 28) +* binding; the specbinding stack; unwind-protects, dynamic: Dynamic Binding; The specbinding Stack; Unwind-Protects. + (line 6) +* bindings, evaluation; stack frames;: Evaluation; Stack Frames; Bindings. + (line 6) +* bit vector: Bit Vector. (line 6) +* bridge, playing: XEmacs From the Outside. + (line 34) +* Buchholz, Martin: XEmacs. (line 6) +* Bufbyte: Character-Related Data Types. + (line 24) +* Bufbytes and Emchars: Bufbytes and Emchars. + (line 6) +* buffer lists: Buffer Lists. (line 6) +* buffer object, the: The Buffer Object. (line 6) +* buffer, the text in a: The Text in a Buffer. + (line 6) +* buffers and textual representation: Buffers and Textual Representation. + (line 6) +* buffers, introduction to: Introduction to Buffers. + (line 6) +* Bufpos: Character-Related Data Types. + (line 47) +* building, XEmacs from the perspective of: XEmacs From the Perspective of Building. + (line 6) +* buttons, checkboxes and radio: Checkboxes and Radio Buttons. + (line 6) +* byte positions, working with character and: Working With Character and Byte Positions. + (line 6) +* Bytecount: Character-Related Data Types. + (line 59) +* bytecount_to_charcount: Working With Character and Byte Positions. + (line 82) +* Bytind: Character-Related Data Types. + (line 59) +* C code, rules when writing new: Rules When Writing New C Code. + (line 6) +* C vs. Lisp: The Lisp Language. (line 6) +* callback routines, the event stream: The Event Stream Callback Routines. + (line 6) +* caller-protects (GCPRO rule): Writing Lisp Primitives. + (line 169) +* case table: Modules for Other Aspects of the Lisp Interpreter and Object System. + (line 44) +* catch and throw: Catch and Throw. (line 6) +* CCL: CCL. (line 6) +* character and byte positions, working with: Working With Character and Byte Positions. + (line 6) +* character encoding, internal: Internal Character Encoding. + (line 6) +* character sets: Character Sets. (line 6) +* character sets and encodings, Mule: MULE Character Sets and Encodings. + (line 6) +* character-related data types: Character-Related Data Types. + (line 6) +* characters, integers and: Integers and Characters. + (line 6) +* Charcount: Character-Related Data Types. + (line 47) +* charcount_to_bytecount: Working With Character and Byte Positions. + (line 88) +* charptr_emchar: Working With Character and Byte Positions. + (line 36) +* charptr_n_addr: Working With Character and Byte Positions. + (line 94) +* checkboxes and radio buttons: Checkboxes and Radio Buttons. + (line 6) +* closer: Lstream Methods. (line 53) +* closure: The XEmacs Object System (Abstractly Speaking). + (line 71) +* code, an example of Mule-aware: An Example of Mule-Aware Code. + (line 6) +* code, general guidelines for writing Mule-aware: General Guidelines for Writing Mule-Aware Code. + (line 6) +* code, rules when writing new C: Rules When Writing New C Code. + (line 6) +* coding conventions: A Reader's Guide to XEmacs Coding Conventions. + (line 6) +* coding for Mule: Coding for Mule. (line 6) +* coding rules, general: General Coding Rules. + (line 6) +* coding rules, naming: A Reader's Guide to XEmacs Coding Conventions. + (line 6) +* command builder, dispatching events; the: Dispatching Events; The Command Builder. + (line 6) +* comments, writing good: Writing Good Comments. + (line 6) +* Common Lisp: The Lisp Language. (line 6) +* compact_string_chars: compact_string_chars. + (line 6) +* compiled function: Compiled Function. (line 6) +* compiler, the Lisp reader and: The Lisp Reader and Compiler. + (line 6) +* cons: Cons. (line 6) +* conservative garbage collection: GCPROing. (line 131) +* consoles; devices; frames; windows: Consoles; Devices; Frames; Windows. + (line 6) +* consoles; devices; frames; windows, introduction to: Introduction to Consoles; Devices; Frames; Windows. + (line 6) +* control flow modules, editor-level: Editor-Level Control Flow Modules. + (line 6) +* conversion to and from external data: Conversion to and from External Data. + (line 6) +* converting events: Converting Events. (line 6) +* copy-on-write: General Coding Rules. + (line 57) +* creating Lisp object types: Techniques for XEmacs Developers. + (line 192) +* critical redisplay sections: Critical Redisplay Sections. + (line 6) +* data dumping: Data dumping. (line 6) +* data types, character-related: Character-Related Data Types. + (line 6) +* DEC_CHARPTR: Working With Character and Byte Positions. + (line 72) +* developers, techniques for XEmacs: Techniques for XEmacs Developers. + (line 6) +* devices; frames; windows, consoles;: Consoles; Devices; Frames; Windows. + (line 6) +* devices; frames; windows, introduction to consoles;: Introduction to Consoles; Devices; Frames; Windows. + (line 6) +* Devin, Matthieu: Lucid Emacs. (line 28) +* dispatching events; the command builder: Dispatching Events; The Command Builder. + (line 6) +* display order of extents: Mathematics of Extent Ordering. + (line 6) +* display-related Lisp objects, modules for other: Modules for other Display-Related Lisp Objects. + (line 6) +* displayable Lisp objects, modules for the basic: Modules for the Basic Displayable Lisp Objects. + (line 6) +* dumping: Dumping. (line 6) +* dumping address allocation: Address allocation. (line 6) +* dumping and its justification, what is: Dumping. (line 9) +* dumping data descriptions: Data descriptions. (line 6) +* dumping object inventory: Object inventory. (line 6) +* dumping overview: Overview. (line 6) +* dumping phase: Dumping phase. (line 6) +* dumping, data: Data dumping. (line 6) +* dumping, file loading: Reloading phase. (line 9) +* dumping, object relocation: Reloading phase. (line 32) +* dumping, pointers: Pointers dumping. (line 6) +* dumping, putting back the pdump_opaques: Reloading phase. (line 21) +* dumping, putting back the pdump_root_objects and pdump_weak_object_chains: Reloading phase. + (line 39) +* dumping, putting back the pdump_root_struct_ptrs: Reloading phase. + (line 26) +* dumping, reloading phase: Reloading phase. (line 6) +* dumping, remaining issues: Remaining issues. (line 6) +* dumping, reorganize the hash tables: Reloading phase. (line 44) +* dumping, the header: The header. (line 6) +* dynamic array: Low-Level Modules. (line 146) +* dynamic binding; the specbinding stack; unwind-protects: Dynamic Binding; The specbinding Stack; Unwind-Protects. + (line 6) +* dynamic scoping: The Lisp Language. (line 6) +* dynamic types: The Lisp Language. (line 6) +* editing operations, modules for standard: Modules for Standard Editing Operations. + (line 6) +* Emacs 19, GNU: GNU Emacs 19. (line 6) +* Emacs 20, GNU: GNU Emacs 20. (line 6) +* Emacs, a history of: A History of Emacs. (line 6) +* Emchar: Character-Related Data Types. + (line 13) +* Emchars, Bufbytes and: Bufbytes and Emchars. + (line 6) +* encoding, internal character: Internal Character Encoding. + (line 6) +* encoding, internal string: Internal String Encoding. + (line 6) +* encodings, internal Mule: Internal Mule Encodings. + (line 6) +* encodings, Mule: Encodings. (line 6) +* encodings, Mule character sets and: MULE Character Sets and Encodings. + (line 6) +* Energize: Lucid Emacs. (line 6) +* Epoch <1>: XEmacs. (line 6) +* Epoch: Lucid Emacs. (line 6) +* error checking: Techniques for XEmacs Developers. + (line 15) +* EUC (Extended Unix Code), Japanese: Japanese EUC (Extended Unix Code). + (line 6) +* evaluation: Evaluation. (line 6) +* evaluation; stack frames; bindings: Evaluation; Stack Frames; Bindings. + (line 6) +* event gathering mechanism, specifics of the: Specifics of the Event Gathering Mechanism. + (line 6) +* event loop functions, other: Other Event Loop Functions. + (line 6) +* event loop, events and the: Events and the Event Loop. + (line 6) +* event stream callback routines, the: The Event Stream Callback Routines. + (line 6) +* event, specifics about the Lisp object: Specifics About the Emacs Event. + (line 6) +* events and the event loop: Events and the Event Loop. + (line 6) +* events, converting: Converting Events. (line 6) +* events, introduction to: Introduction to Events. + (line 6) +* events, main loop: Main Loop. (line 6) +* events; the command builder, dispatching: Dispatching Events; The Command Builder. + (line 6) +* Extbyte: Character-Related Data Types. + (line 66) +* Extcount: Character-Related Data Types. + (line 66) +* Extended Unix Code, Japanese EUC: Japanese EUC (Extended Unix Code). + (line 6) +* extent fragments: Extent Fragments. (line 6) +* extent info, format of the: Format of the Extent Info. + (line 6) +* extent mathematics: Mathematics of Extent Ordering. + (line 6) +* extent ordering <1>: Mathematics of Extent Ordering. + (line 6) +* extent ordering: Extent Ordering. (line 6) +* extents: Extents. (line 6) +* extents, display order: Mathematics of Extent Ordering. + (line 6) +* extents, introduction to: Introduction to Extents. + (line 6) +* extents, markers and: Markers and Extents. (line 6) +* extents, zero-length: Zero-Length Extents. (line 6) +* external data, conversion to and from: Conversion to and from External Data. + (line 6) +* external widget: Modules for Interfacing with X Windows. + (line 93) +* faces: Faces. (line 6) +* file system, modules for interfacing with the: Modules for Interfacing with the File System. + (line 6) +* flusher: Lstream Methods. (line 47) +* fragments, extent: Extent Fragments. (line 6) +* frames; windows, consoles; devices;: Consoles; Devices; Frames; Windows. + (line 6) +* frames; windows, introduction to consoles; devices;: Introduction to Consoles; Devices; Frames; Windows. + (line 6) +* Free Software Foundation: A History of Emacs. (line 6) +* frob blocks, allocation from: Allocation from Frob Blocks. + (line 6) +* FSF: A History of Emacs. (line 6) +* FSF Emacs <1>: GNU Emacs 20. (line 6) +* FSF Emacs: GNU Emacs 19. (line 6) +* function, compiled: Compiled Function. (line 6) +* garbage collection: Garbage Collection. (line 6) +* garbage collection - step by step: Garbage Collection - Step by Step. + (line 6) +* garbage collection protection <1>: GCPROing. (line 6) +* garbage collection protection: Writing Lisp Primitives. + (line 15) +* garbage collection, conservative: GCPROing. (line 131) +* garbage collection, invocation: Invocation. (line 6) +* garbage_collect_1: garbage_collect_1. (line 6) +* gc_sweep: gc_sweep. (line 6) +* GCPROing: GCPROing. (line 6) +* global Lisp variables, adding: Adding Global Lisp Variables. + (line 6) +* glyph instantiation: Glyphs. (line 40) +* glyphs: Glyphs. (line 6) +* GNU Emacs 19: GNU Emacs 19. (line 6) +* GNU Emacs 20: GNU Emacs 20. (line 6) +* Gosling, James <1>: The Lisp Language. (line 6) +* Gosling, James: Through Version 18. (line 6) +* Great Usenet Renaming: Through Version 18. (line 6) +* Hackers (Steven Levy): A History of Emacs. (line 6) +* header files, inline functions: Techniques for XEmacs Developers. + (line 146) +* hierarchy of windows: Window Hierarchy. (line 6) +* history of Emacs, a: A History of Emacs. (line 6) +* Illinois, University of: XEmacs. (line 6) +* INC_CHARPTR: Working With Character and Byte Positions. + (line 72) +* inline functions: Techniques for XEmacs Developers. + (line 108) +* inline functions, headers: Techniques for XEmacs Developers. + (line 146) +* inside, XEmacs from the: XEmacs From the Inside. + (line 6) +* instantiation, glyph: Glyphs. (line 40) +* integers and characters: Integers and Characters. + (line 6) +* interactive: Modules for Standard Editing Operations. + (line 93) +* interfacing with the file system, modules for: Modules for Interfacing with the File System. + (line 6) +* interfacing with the operating system, modules for: Modules for Interfacing with the Operating System. + (line 6) +* interfacing with X Windows, modules for: Modules for Interfacing with X Windows. + (line 6) +* internal character encoding: Internal Character Encoding. + (line 6) +* internal Mule encodings: Internal Mule Encodings. + (line 6) +* internal string encoding: Internal String Encoding. + (line 6) +* internationalization, modules for: Modules for Internationalization. + (line 6) +* interning: The XEmacs Object System (Abstractly Speaking). + (line 302) +* interpreter and object system, modules for other aspects of the Lisp: Modules for Other Aspects of the Lisp Interpreter and Object System. + (line 6) +* ITS (Incompatible Timesharing System): A History of Emacs. (line 6) +* Japanese EUC (Extended Unix Code): Japanese EUC (Extended Unix Code). + (line 6) +* Java: The Lisp Language. (line 6) +* Java vs. Lisp: The Lisp Language. (line 6) +* JIS7: JIS7. (line 6) +* Jones, Kyle: XEmacs. (line 45) +* Kaplan, Simon: XEmacs. (line 6) +* Levy, Steven: A History of Emacs. (line 6) +* library, Lucid Widget: Lucid Widget Library. + (line 6) +* line start cache: Line Start Cache. (line 6) +* Lisp interpreter and object system, modules for other aspects of the: Modules for Other Aspects of the Lisp Interpreter and Object System. + (line 6) +* Lisp language, the: The Lisp Language. (line 6) +* Lisp modules, basic: Basic Lisp Modules. (line 6) +* Lisp object types, creating: Techniques for XEmacs Developers. + (line 192) +* Lisp objects are represented in C, how: How Lisp Objects Are Represented in C. + (line 6) +* Lisp objects, allocation of in XEmacs: Allocation of Objects in XEmacs Lisp. + (line 6) +* Lisp objects, modules for other display-related: Modules for other Display-Related Lisp Objects. + (line 6) +* Lisp objects, modules for the basic displayable: Modules for the Basic Displayable Lisp Objects. + (line 6) +* Lisp primitives, writing: Writing Lisp Primitives. + (line 6) +* Lisp reader and compiler, the: The Lisp Reader and Compiler. + (line 6) +* Lisp vs. C: The Lisp Language. (line 6) +* Lisp vs. Java: The Lisp Language. (line 6) +* low-level allocation: Low-level allocation. + (line 6) +* low-level modules: Low-Level Modules. (line 6) +* lrecords: lrecords. (line 6) +* lstream: Modules for Interfacing with the File System. + (line 20) +* lstream functions: Lstream Functions. (line 6) +* lstream methods: Lstream Methods. (line 6) +* lstream types: Lstream Types. (line 6) +* lstream, creating an: Creating an Lstream. (line 6) +* Lstream_close: Lstream Functions. (line 68) +* Lstream_fgetc: Lstream Functions. (line 45) +* Lstream_flush: Lstream Functions. (line 19) +* Lstream_fputc: Lstream Functions. (line 44) +* Lstream_fungetc: Lstream Functions. (line 46) +* Lstream_getc: Lstream Functions. (line 29) +* Lstream_new: Lstream Functions. (line 8) +* Lstream_putc: Lstream Functions. (line 23) +* Lstream_read: Lstream Functions. (line 50) +* Lstream_reopen: Lstream Functions. (line 71) +* Lstream_rewind: Lstream Functions. (line 77) +* Lstream_set_buffering: Lstream Functions. (line 15) +* Lstream_ungetc: Lstream Functions. (line 34) +* Lstream_unread: Lstream Functions. (line 62) +* Lstream_write: Lstream Functions. (line 56) +* lstreams: Lstreams. (line 6) +* Lucid Emacs: Lucid Emacs. (line 6) +* Lucid Inc.: Lucid Emacs. (line 6) +* Lucid Widget Library: Lucid Widget Library. + (line 6) +* macro hygiene: Techniques for XEmacs Developers. + (line 71) +* main loop: Main Loop. (line 6) +* mark and sweep: Garbage Collection. (line 6) +* mark method <1>: lrecords. (line 107) +* mark method: Modules for Other Aspects of the Lisp Interpreter and Object System. + (line 132) +* mark_object: mark_object. (line 6) +* marker <1>: Lstream Methods. (line 61) +* marker: Marker. (line 6) +* markers and extents: Markers and Extents. (line 6) +* mathematics of extent ordering: Mathematics of Extent Ordering. + (line 6) +* MAX_EMCHAR_LEN: Working With Character and Byte Positions. + (line 14) +* menubars: Menubars. (line 6) +* menus: Menus. (line 6) +* merging attempts: XEmacs. (line 52) +* MIT: A History of Emacs. (line 6) +* Mlynarik, Richard: GNU Emacs 19. (line 68) +* modules for interfacing with the file system: Modules for Interfacing with the File System. + (line 6) +* modules for interfacing with the operating system: Modules for Interfacing with the Operating System. + (line 6) +* modules for interfacing with X Windows: Modules for Interfacing with X Windows. + (line 6) +* modules for internationalization: Modules for Internationalization. + (line 6) +* modules for other aspects of the Lisp interpreter and object system: Modules for Other Aspects of the Lisp Interpreter and Object System. + (line 6) +* modules for other display-related Lisp objects: Modules for other Display-Related Lisp Objects. + (line 6) +* modules for regression testing: Modules for Regression Testing. + (line 6) +* modules for standard editing operations: Modules for Standard Editing Operations. + (line 6) +* modules for the basic displayable Lisp objects: Modules for the Basic Displayable Lisp Objects. + (line 6) +* modules for the redisplay mechanism: Modules for the Redisplay Mechanism. + (line 6) +* modules, a summary of the various XEmacs: A Summary of the Various XEmacs Modules. + (line 6) +* modules, basic Lisp: Basic Lisp Modules. (line 6) +* modules, editor-level control flow: Editor-Level Control Flow Modules. + (line 6) +* modules, low-level: Low-Level Modules. (line 6) +* MS-Windows environment, widget-glyphs in the: Glyphs. (line 107) +* Mule character sets and encodings: MULE Character Sets and Encodings. + (line 6) +* Mule encodings: Encodings. (line 6) +* Mule encodings, internal: Internal Mule Encodings. + (line 6) +* MULE merged XEmacs appears: XEmacs. (line 35) +* Mule, coding for: Coding for Mule. (line 6) +* Mule-aware code, an example of: An Example of Mule-Aware Code. + (line 6) +* Mule-aware code, general guidelines for writing: General Guidelines for Writing Mule-Aware Code. + (line 6) +* NAS: Modules for Interfacing with the Operating System. + (line 135) +* native sound: Modules for Interfacing with the Operating System. + (line 131) +* network connections: Modules for Interfacing with the Operating System. + (line 37) +* network sound: Modules for Interfacing with the Operating System. + (line 135) +* Niksic, Hrvoje: XEmacs. (line 45) +* obarrays: Obarrays. (line 6) +* object system (abstractly speaking), the XEmacs: The XEmacs Object System (Abstractly Speaking). + (line 6) +* object system, modules for other aspects of the Lisp interpreter and: Modules for Other Aspects of the Lisp Interpreter and Object System. + (line 6) +* object types, creating Lisp: Techniques for XEmacs Developers. + (line 192) +* object, the buffer: The Buffer Object. (line 6) +* object, the window: The Window Object. (line 6) +* objects are represented in C, how Lisp: How Lisp Objects Are Represented in C. + (line 6) +* objects in XEmacs Lisp, allocation of: Allocation of Objects in XEmacs Lisp. + (line 6) +* objects, modules for the basic displayable Lisp: Modules for the Basic Displayable Lisp Objects. + (line 6) +* operating system, modules for interfacing with the: Modules for Interfacing with the Operating System. + (line 6) +* outside, XEmacs from the: XEmacs From the Outside. + (line 6) +* pane: Modules for the Basic Displayable Lisp Objects. + (line 63) +* permanent objects: The XEmacs Object System (Abstractly Speaking). + (line 238) +* pi, calculating: XEmacs From the Outside. + (line 34) +* point: Point. (line 6) +* pointers dumping: Pointers dumping. (line 6) +* positions, working with character and byte: Working With Character and Byte Positions. + (line 6) +* primitives, writing Lisp: Writing Lisp Primitives. + (line 6) +* progress bars: Progress Bars. (line 6) +* protection, garbage collection: GCPROing. (line 6) +* pseudo_closer: Lstream Methods. (line 51) +* Purify: Techniques for XEmacs Developers. + (line 6) +* Quantify: Techniques for XEmacs Developers. + (line 6) +* radio buttons, checkboxes and: Checkboxes and Radio Buttons. + (line 6) +* read syntax: The XEmacs Object System (Abstractly Speaking). + (line 252) +* read-eval-print: XEmacs From the Outside. + (line 6) +* reader: Lstream Methods. (line 8) +* reader and compiler, the Lisp: The Lisp Reader and Compiler. + (line 6) +* reader's guide: A Reader's Guide to XEmacs Coding Conventions. + (line 6) +* redisplay mechanism, modules for the: Modules for the Redisplay Mechanism. + (line 6) +* redisplay mechanism, the: The Redisplay Mechanism. + (line 6) +* redisplay piece by piece: Redisplay Piece by Piece. + (line 6) +* redisplay sections, critical: Critical Redisplay Sections. + (line 6) +* regression testing, modules for: Modules for Regression Testing. + (line 6) +* reloading phase: Reloading phase. (line 6) +* relocating allocator: Low-Level Modules. (line 105) +* rename to XEmacs: XEmacs. (line 21) +* represented in C, how Lisp objects are: How Lisp Objects Are Represented in C. + (line 6) +* rewinder: Lstream Methods. (line 38) +* RMS: A History of Emacs. (line 6) +* scanner: Modules for Other Aspects of the Lisp Interpreter and Object System. + (line 52) +* scoping, dynamic: The Lisp Language. (line 6) +* scrollbars: Scrollbars. (line 6) +* seekable_p: Lstream Methods. (line 41) +* selections: Modules for Interfacing with X Windows. + (line 55) +* set_charptr_emchar: Working With Character and Byte Positions. + (line 36) +* Sexton, Harlan: Lucid Emacs. (line 28) +* sound, native: Modules for Interfacing with the Operating System. + (line 131) +* sound, network: Modules for Interfacing with the Operating System. + (line 135) +* SPARCWorks: XEmacs. (line 6) +* specbinding stack; unwind-protects, dynamic binding; the: Dynamic Binding; The specbinding Stack; Unwind-Protects. + (line 6) +* special forms, simple: Simple Special Forms. + (line 6) +* specifiers: Specifiers. (line 6) +* stack frames; bindings, evaluation;: Evaluation; Stack Frames; Bindings. + (line 6) +* Stallman, Richard: A History of Emacs. (line 6) +* string: String. (line 6) +* string encoding, internal: Internal String Encoding. + (line 6) +* subprocesses: Subprocesses. (line 6) +* subprocesses, asynchronous: Modules for Interfacing with the Operating System. + (line 18) +* subprocesses, synchronous: Modules for Interfacing with the Operating System. + (line 13) +* Sun Microsystems: XEmacs. (line 6) +* sweep_bit_vectors_1: sweep_bit_vectors_1. (line 6) +* sweep_lcrecords_1: sweep_lcrecords_1. (line 6) +* sweep_strings: sweep_strings. (line 6) +* symbol: Symbol. (line 6) +* symbol values: Symbol Values. (line 6) +* symbols and variables: Symbols and Variables. + (line 6) +* symbols, introduction to: Introduction to Symbols. + (line 6) +* synchronous subprocesses: Modules for Interfacing with the Operating System. + (line 13) +* tab controls: Tab Controls. (line 6) +* taxes, doing: XEmacs From the Outside. + (line 34) +* techniques for XEmacs developers: Techniques for XEmacs Developers. + (line 6) +* TECO: A History of Emacs. (line 6) +* temporary objects: The XEmacs Object System (Abstractly Speaking). + (line 238) +* testing, regression: Regression Testing XEmacs. + (line 6) +* text in a buffer, the: The Text in a Buffer. + (line 6) +* textual representation, buffers and: Buffers and Textual Representation. + (line 6) +* Thompson, Chuck: XEmacs. (line 6) +* throw, catch and: Catch and Throw. (line 6) +* types, dynamic: The Lisp Language. (line 6) +* types, lstream: Lstream Types. (line 6) +* types, proper use of unsigned: Proper Use of Unsigned Types. + (line 6) +* University of Illinois: XEmacs. (line 6) +* unsigned types, proper use of: Proper Use of Unsigned Types. + (line 6) +* unwind-protects, dynamic binding; the specbinding stack;: Dynamic Binding; The specbinding Stack; Unwind-Protects. + (line 6) +* values, symbol: Symbol Values. (line 6) +* variables, adding global Lisp: Adding Global Lisp Variables. + (line 6) +* variables, symbols and: Symbols and Variables. + (line 6) +* vector: Vector. (line 6) +* vector, bit: Bit Vector. (line 6) +* version 18, through: Through Version 18. (line 6) +* version 19, GNU Emacs: GNU Emacs 19. (line 6) +* version 20, GNU Emacs: GNU Emacs 20. (line 6) +* widget interface, generic: Generic Widget Interface. + (line 6) +* widget library, Lucid: Lucid Widget Library. + (line 6) +* widget-glyphs: Glyphs. (line 104) +* widget-glyphs in the MS-Windows environment: Glyphs. (line 107) +* widget-glyphs in the X environment: Glyphs. (line 112) +* Win-Emacs: XEmacs. (line 6) +* window (in Emacs): Modules for the Basic Displayable Lisp Objects. + (line 63) +* window hierarchy: Window Hierarchy. (line 6) +* window object, the: The Window Object. (line 6) +* window point internals: The Window Object. (line 22) +* windows, consoles; devices; frames;: Consoles; Devices; Frames; Windows. + (line 6) +* windows, introduction to consoles; devices; frames;: Introduction to Consoles; Devices; Frames; Windows. + (line 6) +* Wing, Ben: XEmacs. (line 6) +* writer: Lstream Methods. (line 26) +* writing good comments: Writing Good Comments. + (line 6) +* writing Lisp primitives: Writing Lisp Primitives. + (line 6) +* writing Mule-aware code, general guidelines for: General Guidelines for Writing Mule-Aware Code. + (line 6) +* writing new C code, rules when: Rules When Writing New C Code. + (line 6) +* X environment, widget-glyphs in the: Glyphs. (line 112) +* X Window System, interface to the: Interface to the X Window System. + (line 6) +* X Windows, modules for interfacing with: Modules for Interfacing with X Windows. + (line 6) +* XEmacs: XEmacs. (line 6) +* XEmacs from the inside: XEmacs From the Inside. + (line 6) +* XEmacs from the outside: XEmacs From the Outside. + (line 6) +* XEmacs from the perspective of building: XEmacs From the Perspective of Building. + (line 6) +* XEmacs goes it alone: XEmacs. (line 45) +* XEmacs object system (abstractly speaking), the: The XEmacs Object System (Abstractly Speaking). + (line 6) +* Zawinski, Jamie: Lucid Emacs. (line 28) +* zero-length extents: Zero-Length Extents. (line 6) + + diff -u -r -N xemacs-21.4.18/info/lispref.info xemacs-21.4.19/info/lispref.info --- xemacs-21.4.18/info/lispref.info 1969-12-31 19:00:00.000000000 -0500 +++ xemacs-21.4.19/info/lispref.info 2006-01-28 18:57:51.000000000 -0500 @@ -0,0 +1,919 @@ +This is ../info/lispref.info, produced by makeinfo version 4.8 from +lispref/lispref.texi. + +INFO-DIR-SECTION XEmacs Editor +START-INFO-DIR-ENTRY +* Lispref: (lispref). XEmacs Lisp Reference Manual. +END-INFO-DIR-ENTRY + + Edition History: + + GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU +Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid +Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994 +XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995 +GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp +Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp +Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp +Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May, +November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998 + + Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software +Foundation, Inc. Copyright (C) 1994, 1995 Sun Microsystems, Inc. +Copyright (C) 1995, 1996 Ben Wing. + + Permission is granted to make and distribute verbatim copies of this +manual provided the copyright notice and this permission notice are +preserved on all copies. + + Permission is granted to copy and distribute modified versions of +this manual under the conditions for verbatim copying, provided that the +entire resulting derived work is distributed under the terms of a +permission notice identical to this one. + + Permission is granted to copy and distribute translations of this +manual into another language, under the above conditions for modified +versions, except that this permission notice may be stated in a +translation approved by the Foundation. + + Permission is granted to copy and distribute modified versions of +this manual under the conditions for verbatim copying, provided also +that the section entitled "GNU General Public License" is included +exactly as in the original, and provided that the entire resulting +derived work is distributed under the terms of a permission notice +identical to this one. + + Permission is granted to copy and distribute translations of this +manual into another language, under the above conditions for modified +versions, except that the section entitled "GNU General Public License" +may be included in a translation approved by the Free Software +Foundation instead of in the original English. + + +Indirect: +lispref.info-1: 2366 +lispref.info-2: 300947 +lispref.info-3: 599882 +lispref.info-4: 898613 +lispref.info-5: 1197772 +lispref.info-6: 1495060 +lispref.info-7: 1791353 +lispref.info-8: 2090812 +lispref.info-9: 2361347 + +Tag Table: +(Indirect) +Node: Top2366 +Node: Copying50785 +Node: Introduction69909 +Node: Caveats71495 +Node: Lisp History73179 +Node: Conventions74440 +Node: Some Terms75260 +Node: nil and t75990 +Node: Evaluation Notation77676 +Node: Printing Notation78599 +Node: Error Messages79481 +Node: Buffer Text Notation79931 +Node: Format of Descriptions80810 +Node: A Sample Function Description81673 +Node: A Sample Variable Description85674 +Node: Acknowledgements86596 +Node: Packaging88579 +Node: Package Overview90330 +Node: The User View92514 +Node: The Library Maintainer View98981 +Node: Infrastructure100901 +Node: Control Files104857 +Node: Obtaining106937 +Node: The Package Release Engineer View107463 +Node: Package Terminology108206 +Node: Building Packages111066 +Node: Makefile Targets112295 +Node: Local.rules File114172 +Node: Creating Packages121107 +Node: package-info.in121645 +Node: Makefile126504 +Node: Documenting Packages140268 +Node: Issues141561 +Node: Lisp Data Types141684 +Node: Printed Representation144237 +Node: Comments146286 +Node: Primitive Types147188 +Node: Programming Types148852 +Node: Integer Type150809 +Node: Floating Point Type151855 +Node: Character Type152483 +Node: Symbol Type160396 +Node: Sequence Type163100 +Node: Cons Cell Type164628 +Node: Dotted Pair Notation169121 +Node: Association List Type171255 +Node: Array Type172151 +Node: String Type173626 +Node: Vector Type176318 +Node: Bit Vector Type177099 +Node: Function Type177972 +Node: Macro Type179096 +Node: Primitive Function Type179804 +Node: Compiled-Function Type181341 +Node: Autoload Type181906 +Node: Char Table Type182931 +Node: Hash Table Type183116 +Node: Range Table Type184281 +Node: Weak List Type185145 +Node: Editing Types185306 +Node: Buffer Type186938 +Node: Marker Type188974 +Node: Extent Type189706 +Node: Window Type190983 +Node: Frame Type192403 +Node: Device Type193207 +Node: Console Type194042 +Node: Window Configuration Type195252 +Node: Event Type195959 +Node: Process Type196132 +Node: Stream Type197178 +Node: Keymap Type198312 +Node: Syntax Table Type198861 +Node: Display Table Type199894 +Node: Database Type200345 +Node: Charset Type200522 +Node: Coding System Type200697 +Node: ToolTalk Message Type200892 +Node: ToolTalk Pattern Type201102 +Node: Window-System Types201285 +Node: Face Type202436 +Node: Glyph Type202576 +Node: Specifier Type202741 +Node: Font Instance Type202923 +Node: Color Instance Type203122 +Node: Image Instance Type203328 +Node: Toolbar Button Type203535 +Node: Subwindow Type203737 +Node: X Resource Type203925 +Node: Type Predicates204087 +Node: Equality Predicates213222 +Node: Numbers217921 +Node: Integer Basics219377 +Node: Float Basics221733 +Node: Predicates on Numbers223481 +Node: Comparison of Numbers225124 +Node: Numeric Conversions228958 +Node: Arithmetic Operations230434 +Node: Rounding Operations236587 +Node: Bitwise Operations237709 +Node: Math Functions246666 +Node: Random Numbers249224 +Node: Strings and Characters250998 +Node: String Basics252454 +Node: Predicates for Strings254879 +Node: Creating Strings255651 +Node: Predicates for Characters261003 +Node: Character Codes262086 +Node: Text Comparison263520 +Node: String Conversion266981 +Node: Modifying Strings270662 +Node: String Properties271311 +Node: Formatting Strings271963 +Node: Character Case281556 +Node: Case Tables285082 +Node: Char Tables289070 +Node: Char Table Types290473 +Node: Working With Char Tables292074 +Node: Lists294115 +Node: Cons Cells295241 +Node: Lists as Boxes296584 +Node: List-related Predicates299233 +Node: List Elements300947 +Node: Building Lists306017 +Node: Modifying Lists312010 +Node: Setcar312829 +Node: Setcdr315262 +Node: Rearrangement317795 +Node: Sets And Lists323365 +Node: Association Lists327604 +Ref: Association Lists-Footnote-1336851 +Node: Property Lists337056 +Node: Working With Normal Plists338613 +Node: Working With Lax Plists340971 +Node: Converting Plists To/From Alists343269 +Node: Weak Lists344635 +Node: Sequences Arrays Vectors346812 +Node: Sequence Functions349451 +Node: Arrays353081 +Node: Array Functions356152 +Node: Vectors358636 +Node: Vector Functions360141 +Node: Bit Vectors362723 +Node: Bit Vector Functions363575 +Node: Symbols365886 +Node: Symbol Components366952 +Node: Definitions371142 +Node: Creating Symbols373387 +Node: Symbol Properties380425 +Node: Plists and Alists381959 +Node: Object Plists383719 +Node: Other Plists386496 +Node: Evaluation388310 +Node: Intro Eval389118 +Ref: Intro Eval-Footnote-1392491 +Node: Eval392626 +Node: Forms397059 +Node: Self-Evaluating Forms398226 +Node: Symbol Forms399750 +Node: Classifying Lists400678 +Node: Function Indirection401445 +Node: Function Forms404556 +Node: Macro Forms405564 +Node: Special Forms407175 +Node: Autoloading409495 +Node: Quoting410004 +Node: Control Structures411373 +Node: Sequencing412997 +Node: Conditionals415872 +Node: Combining Conditions419304 +Node: Iteration422584 +Node: Nonlocal Exits424371 +Node: Catch and Throw425079 +Node: Examples of Catch428931 +Node: Errors430951 +Node: Signaling Errors432451 +Node: Processing of Errors441173 +Node: Handling Errors443468 +Node: Error Symbols450693 +Node: Cleanups454665 +Node: Variables458455 +Node: Global Variables460241 +Node: Constant Variables461324 +Node: Local Variables461957 +Node: Void Variables466918 +Node: Defining Variables470423 +Node: Accessing Variables477597 +Node: Setting Variables479000 +Node: Variable Scoping483499 +Node: Scope485105 +Node: Extent486637 +Node: Impl of Scope488127 +Node: Using Scoping490101 +Node: Buffer-Local Variables491634 +Node: Intro to Buffer-Local492477 +Node: Creating Buffer-Local495031 +Node: Default Value500940 +Node: Variable Aliases504078 +Node: Functions and Commands505941 +Node: What Is a Function507077 +Node: Lambda Expressions511649 +Node: Lambda Components512579 +Node: Simple Lambda514418 +Node: Argument List516086 +Node: Function Documentation519825 +Node: Function Names521778 +Node: Defining Functions524371 +Node: Calling Functions527414 +Node: Mapping Functions531276 +Node: Anonymous Functions533948 +Node: Function Cells537214 +Node: Inline Functions542036 +Node: Related Topics543866 +Node: Macros544941 +Node: Simple Macro546241 +Node: Expansion546983 +Node: Compiling Macros549965 +Node: Defining Macros551808 +Node: Backquote553133 +Node: Problems with Macros555532 +Node: Argument Evaluation556233 +Node: Surprising Local Vars559149 +Node: Eval During Expansion561225 +Node: Repeated Expansion562929 +Node: Customization564851 +Node: Common Keywords565323 +Node: Group Definitions568174 +Node: Variable Definitions570375 +Node: Customization Types575373 +Node: Simple Types576815 +Node: Composite Types578983 +Node: Splicing into Lists583684 +Node: Type Keywords585530 +Node: Loading589062 +Node: How Programs Do Loading590740 +Node: Autoload599882 +Node: Repeated Loading605960 +Node: Named Features608070 +Node: Unloading614473 +Node: Hooks for Loading616638 +Node: Byte Compilation617366 +Node: Speed of Byte-Code619436 +Node: Compilation Functions620635 +Node: Compilation Options627394 +Node: Docs and Compilation637342 +Node: Dynamic Loading640018 +Node: Eval During Compile642406 +Node: Compiled-Function Objects643680 +Node: Disassembly648496 +Node: Different Behavior655605 +Node: Debugging656957 +Node: Debugger658372 +Node: Error Debugging659524 +Node: Infinite Loops662291 +Node: Function Debugging663547 +Node: Explicit Debug666340 +Node: Using Debugger667122 +Node: Debugger Commands668995 +Node: Invoking the Debugger673323 +Node: Internals of Debugger677235 +Node: Syntax Errors682119 +Node: Excess Open683374 +Node: Excess Close685260 +Node: Compilation Errors686692 +Node: Edebug687987 +Node: Using Edebug690102 +Node: Instrumenting692810 +Node: Edebug Execution Modes696310 +Node: Jumping699431 +Node: Edebug Misc701786 +Node: Breakpoints703186 +Node: Global Break Condition706003 +Node: Embedded Breakpoints706973 +Node: Trapping Errors707943 +Node: Edebug Views710030 +Node: Edebug Eval712007 +Node: Eval List713195 +Node: Reading in Edebug716593 +Node: Printing in Edebug717405 +Node: Tracing719133 +Node: Coverage Testing721034 +Node: The Outside Context723089 +Node: Checking Whether to Stop724051 +Node: Edebug Display Update724715 +Node: Edebug Recursive Edit726755 +Node: Instrumenting Macro Calls728427 +Node: Specification List730917 +Node: Backtracking740347 +Node: Debugging Backquote742302 +Node: Specification Examples746015 +Node: Edebug Options748084 +Node: Read and Print753452 +Node: Streams Intro754432 +Node: Input Streams756457 +Node: Input Functions761340 +Node: Output Streams763400 +Node: Output Functions767413 +Node: Output Variables771726 +Node: Minibuffers776535 +Node: Intro to Minibuffers777690 +Node: Text from Minibuffer779885 +Node: Object from Minibuffer784989 +Node: Minibuffer History789053 +Node: Completion792048 +Node: Basic Completion794030 +Node: Minibuffer Completion798907 +Node: Completion Commands802476 +Node: High-Level Completion807155 +Node: Reading File Names811858 +Node: Programmed Completion815513 +Node: Yes-or-No Queries817906 +Node: Multiple Queries823575 +Node: Reading a Password827650 +Node: Minibuffer Misc829003 +Node: Command Loop833908 +Node: Command Overview835255 +Node: Defining Commands838541 +Node: Using Interactive839296 +Node: Interactive Codes844084 +Node: Interactive Examples849887 +Node: Interactive Call851197 +Node: Command Loop Info856583 +Node: Events861576 +Node: Event Types863045 +Node: Event Contents864979 +Node: Event Predicates869468 +Node: Accessing Mouse Event Positions870808 +Node: Frame-Level Event Position Info871518 +Node: Window-Level Event Position Info872576 +Node: Event Text Position Info874359 +Node: Event Glyph Position Info876872 +Node: Event Toolbar Position Info878214 +Node: Other Event Position Info878905 +Node: Accessing Other Event Info879333 +Node: Working With Events880973 +Node: Converting Events886918 +Node: Reading Input890331 +Node: Key Sequence Input891340 +Node: Reading One Event893967 +Node: Dispatching an Event896806 +Node: Quoted Character Input897272 +Node: Peeking and Discarding898613 +Node: Waiting902535 +Node: Quitting904858 +Node: Prefix Command Arguments909276 +Node: Recursive Editing914321 +Node: Disabling Commands919129 +Node: Command History921209 +Node: Keyboard Macros922956 +Node: Keymaps925186 +Node: Keymap Terminology926766 +Node: Format of Keymaps929702 +Node: Creating Keymaps930121 +Node: Inheritance and Keymaps932203 +Node: Key Sequences934586 +Node: Prefix Keys939390 +Node: Active Keymaps942978 +Node: Key Lookup952359 +Node: Functions for Key Lookup957529 +Node: Changing Key Bindings963234 +Node: Key Binding Commands970358 +Node: Scanning Keymaps972436 +Node: Other Keymap Functions981020 +Node: Menus981656 +Node: Menu Format982254 +Node: Menubar Format990908 +Node: Menubar991540 +Node: Modifying Menus994671 +Node: Menu Filters1000031 +Node: Pop-Up Menus1001937 +Node: Menu Accelerators1004285 +Node: Creating Menu Accelerators1005048 +Node: Keyboard Menu Traversal1006419 +Node: Menu Accelerator Functions1007158 +Node: Buffers Menu1010272 +Node: Dialog Boxes1011577 +Node: Dialog Box Format1011750 +Node: Dialog Box Functions1013182 +Node: Toolbar1013590 +Node: Toolbar Intro1014031 +Node: Creating Toolbar1016439 +Node: Toolbar Descriptor Format1017367 +Node: Specifying the Toolbar1021873 +Node: Other Toolbar Variables1025495 +Node: Gutter1029943 +Node: Gutter Intro1030535 +Node: Creating Gutter1032545 +Node: Gutter Descriptor Format1035445 +Node: Specifying a Gutter1039911 +Node: Other Gutter Variables1043461 +Node: Common Gutter Widgets1047868 +Node: Buffer Tabs1048867 +Node: Progress Bars1049019 +Node: Scrollbars1049175 +Node: Drag and Drop1049313 +Node: Supported Protocols1050392 +Node: OffiX DND1050902 +Node: CDE dt1051920 +Node: MSWindows OLE1052522 +Node: Loose ends1052704 +Node: Drop Interface1053107 +Node: Drag Interface1054137 +Node: Modes1054318 +Node: Major Modes1055272 +Node: Major Mode Conventions1058749 +Node: Example Major Modes1065249 +Node: Auto Major Mode1073264 +Node: Mode Help1080737 +Node: Derived Modes1081851 +Node: Minor Modes1084156 +Node: Minor Mode Conventions1085465 +Node: Keymaps and Minor Modes1088339 +Node: Modeline Format1089185 +Node: Modeline Data1090961 +Node: Modeline Variables1096126 +Node: %-Constructs1100861 +Node: Hooks1103859 +Node: Documentation1112117 +Node: Documentation Basics1113543 +Node: Accessing Documentation1116601 +Node: Keys in Documentation1122868 +Node: Describing Characters1126339 +Node: Help Functions1128698 +Node: Obsoleteness1135155 +Node: Files1138317 +Node: Visiting Files1140245 +Node: Visiting Functions1141757 +Node: Subroutines of Visiting1146934 +Node: Saving Buffers1149020 +Node: Reading from Files1155130 +Node: Writing to Files1157299 +Node: File Locks1160025 +Node: Information about Files1163103 +Node: Testing Accessibility1163871 +Node: Kinds of Files1167629 +Node: Truenames1169324 +Node: File Attributes1170338 +Node: Changing File Attributes1175451 +Node: File Names1180868 +Node: File Name Components1182447 +Node: Directory Names1184907 +Node: Relative File Names1188152 +Node: File Name Expansion1189133 +Node: Unique File Names1192902 +Node: File Name Completion1194530 +Node: User Name Completion1197772 +Node: Contents of Directories1199193 +Node: Create/Delete Dirs1202516 +Node: Magic File Names1203633 +Node: Partial Files1209295 +Node: Intro to Partial Files1209535 +Node: Creating a Partial File1210788 +Node: Detached Partial Files1211741 +Node: Format Conversion1212876 +Node: Files and MS-DOS1218389 +Node: Backups and Auto-Saving1220468 +Node: Backup Files1221146 +Node: Making Backups1222550 +Node: Rename or Copy1225318 +Node: Numbered Backups1227825 +Node: Backup Names1230076 +Node: Auto-Saving1233373 +Node: Reverting1241559 +Node: Buffers1244907 +Node: Buffer Basics1246326 +Node: Current Buffer1248383 +Node: Buffer Names1253096 +Node: Buffer File Name1256304 +Node: Buffer Modification1260437 +Node: Modification Time1262691 +Node: Read Only Buffers1266078 +Node: The Buffer List1269328 +Node: Creating Buffers1274146 +Node: Killing Buffers1276301 +Node: Indirect Buffers1280127 +Node: Windows1282713 +Node: Basic Windows1284194 +Node: Splitting Windows1287300 +Node: Deleting Windows1292627 +Node: Selecting Windows1296556 +Node: Cyclic Window Ordering1300791 +Node: Buffers and Windows1305957 +Node: Displaying Buffers1307745 +Node: Choosing Window1313095 +Node: Window Point1321038 +Node: Window Start1323117 +Node: Vertical Scrolling1327899 +Node: Horizontal Scrolling1334104 +Node: Size of Window1337646 +Node: Position of Window1342380 +Node: Resizing Windows1344646 +Node: Window Configurations1350102 +Node: Frames1353604 +Node: Creating Frames1355949 +Node: Frame Properties1357297 +Node: Property Access1358120 +Node: Initial Properties1359042 +Node: X Frame Properties1361542 +Node: Size and Position1366187 +Node: Frame Name1368202 +Node: Frame Titles1369129 +Node: Deleting Frames1370963 +Node: Finding All Frames1371946 +Node: Frames and Windows1375189 +Node: Minibuffers and Frames1377985 +Node: Input Focus1378911 +Node: Visibility of Frames1382028 +Node: Raising and Lowering1384032 +Node: Frame Configurations1386423 +Node: Frame Hooks1387491 +Node: Consoles and Devices1389311 +Node: Basic Console Functions1392059 +Node: Basic Device Functions1392494 +Node: Console Types and Device Classes1393354 +Node: Connecting to a Console or Device1395634 +Node: The Selected Console and Device1397837 +Node: Console and Device I/O1398877 +Node: Positions1399655 +Node: Point1400628 +Node: Motion1403731 +Node: Character Motion1404505 +Node: Word Motion1406757 +Node: Buffer End Motion1408161 +Node: Text Lines1409711 +Node: Screen Lines1414636 +Node: List Motion1418713 +Node: Skipping Characters1422196 +Node: Excursions1424408 +Node: Narrowing1427460 +Node: Markers1432782 +Node: Overview of Markers1433691 +Node: Predicates on Markers1438365 +Node: Creating Markers1439623 +Node: Information from Markers1443715 +Node: Changing Markers1444812 +Node: The Mark1446349 +Node: The Region1454871 +Node: Text1460605 +Node: Near Point1463307 +Node: Buffer Contents1467499 +Node: Comparing Text1468894 +Node: Insertion1470310 +Node: Commands for Insertion1474212 +Node: Deletion1477118 +Node: User-Level Deletion1480780 +Node: The Kill Ring1484892 +Node: Kill Ring Concepts1487073 +Node: Kill Functions1488138 +Node: Yank Commands1490074 +Node: Low-Level Kill Ring1491958 +Node: Internals of Kill Ring1495060 +Node: Undo1497854 +Node: Maintaining Undo1502201 +Node: Filling1504833 +Node: Margins1510846 +Node: Auto Filling1514892 +Node: Sorting1516083 +Node: Columns1525414 +Node: Indentation1528506 +Node: Primitive Indent1529294 +Node: Mode-Specific Indent1530635 +Node: Region Indent1533185 +Node: Relative Indent1536149 +Node: Indent Tabs1538546 +Node: Motion by Indent1539882 +Node: Case Changes1540677 +Node: Text Properties1544025 +Node: Examining Properties1545890 +Node: Changing Properties1547790 +Node: Property Search1551398 +Node: Special Properties1556156 +Node: Saving Properties1556450 +Node: Fields1559622 +Node: Substitution1565314 +Node: Registers1568555 +Node: Transposition1571151 +Node: Change Hooks1572055 +Node: Transformations1574109 +Node: Searching and Matching1579196 +Node: String Search1580330 +Node: Regular Expressions1585282 +Node: Syntax of Regexps1586656 +Node: Regexp Example1602189 +Node: Regexp Search1604370 +Node: POSIX Regexps1610650 +Node: Search and Replace1612738 +Node: Match Data1616115 +Node: Simple Match Data1617252 +Node: Replacing Match1621501 +Node: Entire Match Data1624194 +Node: Saving Match Data1626445 +Node: Searching and Case1627845 +Node: Standard Regexps1629889 +Node: Syntax Tables1632098 +Node: Syntax Basics1633215 +Node: Syntax Descriptors1636202 +Node: Syntax Class Table1638059 +Node: Syntax Flags1644266 +Node: Syntax Table Functions1648676 +Node: Motion and Syntax1652927 +Node: Parsing Expressions1654389 +Node: Standard Syntax Tables1660499 +Node: Syntax Table Internals1661354 +Node: Abbrevs1662387 +Node: Abbrev Mode1664194 +Node: Abbrev Tables1664923 +Node: Defining Abbrevs1666474 +Node: Abbrev Files1668405 +Node: Abbrev Expansion1670200 +Node: Standard Abbrev Tables1674829 +Node: Extents1676001 +Node: Intro to Extents1677247 +Node: Creating and Modifying Extents1681246 +Node: Extent Endpoints1682841 +Node: Finding Extents1686115 +Node: Mapping Over Extents1690248 +Node: Extent Properties1696382 +Node: Detached Extents1706635 +Node: Extent Parents1708505 +Node: Duplicable Extents1710210 +Node: Extents and Events1713438 +Node: Atomic Extents1715411 +Node: Specifiers1715867 +Node: Introduction to Specifiers1718003 +Node: Simple Specifier Usage1722194 +Node: Specifiers In-Depth1728607 +Node: Specifier Instancing1735251 +Node: Specifier Types1738520 +Node: Adding Specifications1743611 +Node: Retrieving Specifications1755119 +Node: Specifier Tag Functions1758877 +Node: Specifier Instancing Functions1762126 +Node: Specifier Examples1766994 +Node: Creating Specifiers1774585 +Node: Specifier Validation Functions1778947 +Node: Other Specification Functions1781356 +Node: Faces and Window-System Objects1785264 +Node: Faces1785594 +Node: Merging Faces1787218 +Node: Basic Face Functions1789190 +Node: Face Properties1791353 +Node: Face Convenience Functions1801686 +Node: Other Face Display Functions1805445 +Node: Fonts1806274 +Node: Font Specifiers1806982 +Node: Font Instances1808183 +Node: Font Instance Names1809166 +Node: Font Instance Size1810024 +Node: Font Instance Characteristics1811327 +Node: Font Convenience Functions1812525 +Node: Colors1813832 +Node: Color Specifiers1814282 +Node: Color Instances1816659 +Node: Color Instance Properties1817415 +Node: Color Convenience Functions1818057 +Node: Glyphs1819126 +Node: Glyph Intro1820202 +Node: Images1823219 +Node: Image Specifiers1823582 +Node: Image Instantiator Conversion1833189 +Node: Image Instantiator Formats1834733 +Node: Image Instances1849205 +Node: Image Instance Types1849965 +Node: Image Instance Functions1852955 +Node: Using Glyphs1860449 +Node: Creating Glyphs1864588 +Node: Buffer Glyphs1869820 +Node: Redisplay Glyphs1871256 +Node: Frame Glyphs1873902 +Node: External Glyphs1876050 +Node: Native GUI Widgets1880930 +Node: Introduction to Widgets1881596 +Node: Lisp API to Native Widgets1882613 +Node: Layouts1884217 +Node: Primitive Widgets1887753 +Node: Subwindows1888460 +Node: Manipulating Glyphs1888723 +Node: Glyph Properties1889417 +Node: Glyph Convenience Functions1898751 +Node: Glyph Dimensions1902724 +Node: Glyph Types1903846 +Node: Glyph Examples1905636 +Node: Annotations1913901 +Node: Annotation Basics1914920 +Node: Annotation Primitives1918865 +Node: Annotation Properties1920217 +Node: Locating Annotations1923296 +Node: Margin Primitives1924147 +Node: Annotation Hooks1926054 +Node: Display1926721 +Node: Refresh Screen1927702 +Node: Truncation1929907 +Node: The Echo Area1932442 +Node: Warnings1938872 +Node: Invisible Text1943261 +Node: Selective Display1945983 +Node: Overlay Arrow1950078 +Node: Temporary Displays1951440 +Node: Blinking1955502 +Node: Usual Display1957698 +Node: Display Tables1960259 +Node: Display Table Format1961072 +Node: Active Display Table1962528 +Node: Character Descriptors1966537 +Node: Beeping1967307 +Node: Hash Tables1972093 +Node: Introduction to Hash Tables1972708 +Node: Working With Hash Tables1979282 +Node: Weak Hash Tables1980414 +Node: Range Tables1982438 +Node: Introduction to Range Tables1983131 +Node: Working With Range Tables1983589 +Node: Databases1984563 +Node: Connecting to a Database1984869 +Node: Working With a Database1985989 +Node: Other Database Functions1986877 +Node: Processes1987460 +Node: Subprocess Creation1989688 +Node: Synchronous Processes1993150 +Node: MS-DOS Subprocesses1999821 +Node: Asynchronous Processes2000904 +Node: Deleting Processes2005231 +Node: Process Information2007112 +Node: Input to Processes2011222 +Node: Signals to Processes2013907 +Node: Output from Processes2018736 +Node: Process Buffers2019555 +Node: Filter Functions2022449 +Node: Accepting Output2028053 +Node: Sentinels2029592 +Node: Process Window Size2033094 +Node: Transaction Queues2033456 +Node: Network2035166 +Node: System Interface2037810 +Node: Starting Up2039083 +Node: Start-up Summary2039684 +Node: Init File2043255 +Node: Terminal-Specific2045651 +Node: Command Line Arguments2048824 +Node: Getting Out2052329 +Node: Killing XEmacs2052905 +Node: Suspending XEmacs2054587 +Node: System Environment2057950 +Node: User Identification2064131 +Node: Time of Day2067678 +Node: Time Conversion2070475 +Node: Timers2075727 +Node: Terminal Input2077909 +Node: Input Modes2078419 +Node: Translating Input2080894 +Node: Recording Input2085062 +Node: Terminal Output2087180 +Node: Flow Control2090812 +Node: Batch Mode2094785 +Node: X-Windows2096177 +Node: X Selections2097052 +Node: X Server2099815 +Node: Resources2100273 +Node: Server Data2105600 +Node: Grabs2106821 +Node: X Miscellaneous2108419 +Node: ToolTalk Support2110821 +Node: XEmacs ToolTalk API Summary2111044 +Node: Sending Messages2112351 +Node: Example of Sending Messages2112612 +Node: Elisp Interface for Sending Messages2113675 +Node: Receiving Messages2120303 +Node: Example of Receiving Messages2120536 +Node: Elisp Interface for Receiving Messages2121373 +Node: LDAP Support2125262 +Node: Building XEmacs with LDAP support2125759 +Node: XEmacs LDAP API2126743 +Node: LDAP Variables2127802 +Node: The High-Level LDAP API2130421 +Node: The Low-Level LDAP API2133919 +Node: The LDAP Lisp Object2134761 +Node: Opening and Closing a LDAP Connection2135334 +Node: Low-level Operations on a LDAP Server2137169 +Node: LDAP Internationalization2139912 +Node: LDAP Internationalization Variables2140829 +Node: Encoder/Decoder Functions2142584 +Node: Syntax of Search Filters2143653 +Node: PostgreSQL Support2144957 +Node: Building XEmacs with PostgreSQL support2145355 +Node: XEmacs PostgreSQL libpq API2146709 +Node: libpq Lisp Variables2148595 +Node: libpq Lisp Symbols and DataTypes2151618 +Node: Synchronous Interface Functions2164913 +Node: Asynchronous Interface Functions2169436 +Node: Large Object Support2172967 +Node: Other libpq Functions2173610 +Node: Unimplemented libpq Functions2176667 +Node: XEmacs PostgreSQL libpq Examples2182029 +Node: Internationalization2188122 +Node: I18N Levels 1 and 22188471 +Node: I18N Level 32189184 +Node: Level 3 Basics2189475 +Node: Level 3 Primitives2190320 +Node: Dynamic Messaging2191945 +Node: Domain Specification2192419 +Node: Documentation String Extraction2194103 +Node: I18N Level 42195032 +Node: MULE2195231 +Node: Internationalization Terminology2196283 +Node: Charsets2208489 +Node: Charset Properties2209193 +Node: Basic Charset Functions2213919 +Node: Charset Property Functions2216121 +Node: Predefined Charsets2218363 +Node: MULE Characters2221294 +Node: Composite Characters2222184 +Node: Coding Systems2223462 +Node: Coding System Types2225610 +Node: ISO 20222229605 +Node: EOL Conversion2241871 +Node: Coding System Properties2243057 +Node: Basic Coding System Functions2247394 +Node: Coding System Property Functions2249450 +Node: Encoding and Decoding Text2250025 +Node: Detection of Textual Encoding2251177 +Node: Big5 and Shift-JIS Functions2252733 +Node: Predefined Coding Systems2253900 +Node: CCL2266006 +Node: CCL Syntax2269129 +Node: CCL Statements2270716 +Node: CCL Expressions2275360 +Node: Calling CCL2277910 +Node: CCL Example2280930 +Node: Four bits to ASCII2283432 +Node: URI Encoding constants2285024 +Node: Numeric to ASCII-hexadecimal conversion2286064 +Node: Characters to be preserved2287435 +Ref: Characters to be preserved-Footnote-12288972 +Node: The program to decode to internal format2289103 +Node: The program to encode from internal format2291816 +Node: The actual coding system2293507 +Node: Category Tables2294891 +Node: Tips2297264 +Node: Style Tips2297925 +Node: Compilation Tips2307808 +Node: Documentation Tips2309717 +Node: Comment Tips2315231 +Node: Library Headers2318240 +Node: Building XEmacs and Object Allocation2322201 +Node: Building XEmacs2323103 +Node: Pure Storage2329693 +Node: Garbage Collection2332344 +Node: Standard Errors2343191 +Node: Standard Buffer-Local Variables2347419 +Node: Standard Keymaps2350073 +Node: Standard Hooks2353827 +Node: Index2361347 + +End Tag Table diff -u -r -N xemacs-21.4.18/info/lispref.info-1 xemacs-21.4.19/info/lispref.info-1 --- xemacs-21.4.18/info/lispref.info-1 1969-12-31 19:00:00.000000000 -0500 +++ xemacs-21.4.19/info/lispref.info-1 2006-01-28 18:57:51.000000000 -0500 @@ -0,0 +1,7437 @@ +This is ../info/lispref.info, produced by makeinfo version 4.8 from +lispref/lispref.texi. + +INFO-DIR-SECTION XEmacs Editor +START-INFO-DIR-ENTRY +* Lispref: (lispref). XEmacs Lisp Reference Manual. +END-INFO-DIR-ENTRY + + Edition History: + + GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU +Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid +Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994 +XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995 +GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp +Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp +Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp +Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May, +November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998 + + Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software +Foundation, Inc. Copyright (C) 1994, 1995 Sun Microsystems, Inc. +Copyright (C) 1995, 1996 Ben Wing. + + Permission is granted to make and distribute verbatim copies of this +manual provided the copyright notice and this permission notice are +preserved on all copies. + + Permission is granted to copy and distribute modified versions of +this manual under the conditions for verbatim copying, provided that the +entire resulting derived work is distributed under the terms of a +permission notice identical to this one. + + Permission is granted to copy and distribute translations of this +manual into another language, under the above conditions for modified +versions, except that this permission notice may be stated in a +translation approved by the Foundation. + + Permission is granted to copy and distribute modified versions of +this manual under the conditions for verbatim copying, provided also +that the section entitled "GNU General Public License" is included +exactly as in the original, and provided that the entire resulting +derived work is distributed under the terms of a permission notice +identical to this one. + + Permission is granted to copy and distribute translations of this +manual into another language, under the above conditions for modified +versions, except that the section entitled "GNU General Public License" +may be included in a translation approved by the Free Software +Foundation instead of in the original English. + + +File: lispref.info, Node: Top, Next: Copying, Prev: (dir), Up: (dir) + + This Info file contains the third edition of the XEmacs Lisp +Reference Manual, corresponding to XEmacs version 21.0. + +* Menu: + +* Copying:: Conditions for copying and changing XEmacs. +* Introduction:: Introduction and conventions used. + +* Packaging:: Lisp library administrative infrastructure. + +* Lisp Data Types:: Data types of objects in XEmacs Lisp. +* Numbers:: Numbers and arithmetic functions. +* Strings and Characters:: Strings, and functions that work on them. +* Lists:: Lists, cons cells, and related functions. +* Sequences Arrays Vectors:: Lists, strings and vectors are called sequences. + Certain functions act on any kind of sequence. + The description of vectors is here as well. +* Symbols:: Symbols represent names, uniquely. + +* Evaluation:: How Lisp expressions are evaluated. +* Control Structures:: Conditionals, loops, nonlocal exits. +* Variables:: Using symbols in programs to stand for values. + +* Functions and Commands:: A function is a Lisp program that can be + invoked from other functions. + +* Macros:: Macros are a way to extend the Lisp language. +* Customization:: Writing customization declarations. + +* Loading:: Reading files of Lisp code into Lisp. +* Byte Compilation:: Compilation makes programs run faster. +* Debugging:: Tools and tips for debugging Lisp programs. + +* Read and Print:: Converting Lisp objects to text and back. +* Minibuffers:: Using the minibuffer to read input. +* Command Loop:: How the editor command loop works, + and how you can call its subroutines. +* Keymaps:: Defining the bindings from keys to commands. +* Menus:: Defining pull-down and pop-up menus. +* Dialog Boxes:: Creating dialog boxes. +* Toolbar:: Controlling the toolbar. +* Gutter:: Controlling the gutter. +* Scrollbars:: Controlling the scrollbars. +* Drag and Drop:: Generic API to inter-application communication + via specific protocols. +* Modes:: Defining major and minor modes. +* Documentation:: Writing and using documentation strings. + +* Files:: Accessing files. +* Backups and Auto-Saving:: Controlling how backups and auto-save + files are made. +* Buffers:: Creating and using buffer objects. +* Windows:: Manipulating windows and displaying buffers. +* Frames:: Making multiple X windows. +* Consoles and Devices:: Opening frames on multiple TTY's or X displays. +* Positions:: Buffer positions and motion functions. +* Markers:: Markers represent positions and update + automatically when the text is changed. + +* Text:: Examining and changing text in buffers. +* Searching and Matching:: Searching buffers for strings or regexps. +* Syntax Tables:: The syntax table controls word and list parsing. +* Abbrevs:: How Abbrev mode works, and its data structures. + +* Extents:: Extents are regions of text with particular + display characteristics. +* Specifiers:: How faces and glyphs are specified. +* Faces and Window-System Objects:: + A face is a set of display characteristics + specifying how text is to be displayed. +* Glyphs:: General interface to pixmaps displayed in a + buffer or frame. +* Annotations:: Higher-level interface to glyphs in a buffer. +* Display:: Parameters controlling screen usage. + The bell. Waiting for input. + +* Hash Tables:: Fast data structures for mappings. +* Range Tables:: Keeping track of ranges of numbers. +* Databases:: An interface to standard DBM and DB databases. + +* Processes:: Running and communicating with subprocesses. +* System Interface:: Getting the user id, system type, environment + variables, and other such things. +* X-Windows:: Functions specific to the X Window System. +* ToolTalk Support:: Interfacing with the ToolTalk message service. +* LDAP Support:: Interfacing with the Lightweight Directory + Access Protocol. +* PostgreSQL Support:: Interfacing to the PostgreSQL libpq library. +* Internationalization:: How Emacs supports different languages and + cultural conventions. +* MULE:: Specifics of the Asian-language support. + +Appendices + +* Tips:: Advice for writing Lisp programs. +* Building XEmacs and Object Allocation:: + Behind-the-scenes information about XEmacs. +* Standard Errors:: List of all error symbols. +* Standard Buffer-Local Variables:: List of variables local in all buffers. +* Standard Keymaps:: List of standard keymaps. +* Standard Hooks:: List of standard hook variables. + +* Index:: Index including concepts, functions, variables, + and other terms. + + --- The Detailed Node Listing --- + +Here are other nodes that are inferiors of those already listed, +mentioned here so you can get to them in one step: + +Introduction + +* Caveats:: Flaws and a request for help. +* Lisp History:: XEmacs Lisp is descended from Maclisp. +* Conventions:: How the manual is formatted. +* Acknowledgements:: The authors, editors, and sponsors of this manual. + +Conventions + +* Some Terms:: Explanation of terms we use in this manual. +* nil and t:: How the symbols `nil' and `t' are used. +* Evaluation Notation:: The format we use for examples of evaluation. +* Printing Notation:: The format we use for examples that print output. +* Error Messages:: The format we use for examples of errors. +* Buffer Text Notation:: The format we use for buffer contents in examples. +* Format of Descriptions:: Notation for describing functions, variables, etc. + +Format of Descriptions + +* A Sample Function Description:: +* A Sample Variable Description:: + +Packaging + +* Package Overview:: Lisp Libraries and Packages. +* Package Terminology:: Basic stuff. +* Building Packages:: Turn packaged source into a tarball. +* Local.rules File:: Tell the XEmacs Packaging System about your host. +* Creating Packages:: Tell the XEmacs Packaging System about your package. +* Issues:: + +Package Overview + +* The User View:: +* The Library Maintainer View:: +* The Package Release Engineer View:: + +The Library Maintainer's View + +* Infrastructure:: Global Makefiles and common rules. +* Control Files:: Package-specific Makefiles and administrative files. +* Obtaining:: Obtaining the XEmacs Packaging System and utilities. + +Creating Packages + +* package-info.in:: package-info.in +* Makefile:: `Makefile' +* Makefile Targets:: + +Lisp Data Types + +* Printed Representation:: How Lisp objects are represented as text. +* Comments:: Comments and their formatting conventions. +* Programming Types:: Types found in all Lisp systems. +* Editing Types:: Types specific to XEmacs. +* Type Predicates:: Tests related to types. +* Equality Predicates:: Tests of equality between any two objects. + +Programming Types + +* Integer Type:: Numbers without fractional parts. +* Floating Point Type:: Numbers with fractional parts and with a large range. +* Character Type:: The representation of letters, numbers and + control characters. +* Sequence Type:: Both lists and arrays are classified as sequences. +* Cons Cell Type:: Cons cells, and lists (which are made from cons cells). +* Array Type:: Arrays include strings and vectors. +* String Type:: An (efficient) array of characters. +* Vector Type:: One-dimensional arrays. +* Symbol Type:: A multi-use object that refers to a function, + variable, property list, or itself. +* Function Type:: A piece of executable code you can call from elsewhere. +* Macro Type:: A method of expanding an expression into another + expression, more fundamental but less pretty. +* Primitive Function Type:: A function written in C, callable from Lisp. +* Compiled-Function Type:: A function written in Lisp, then compiled. +* Autoload Type:: A type used for automatically loading seldom-used + functions. + +Cons Cell Type + +* Dotted Pair Notation:: An alternative syntax for lists. +* Association List Type:: A specially constructed list. + +Editing Types + +* Buffer Type:: The basic object of editing. +* Window Type:: What makes buffers visible. +* Window Configuration Type:: Save what the screen looks like. +* Marker Type:: A position in a buffer. +* Process Type:: A process running on the underlying OS. +* Stream Type:: Receive or send characters. +* Keymap Type:: What function a keystroke invokes. +* Syntax Table Type:: What a character means. + +Numbers + +* Integer Basics:: Representation and range of integers. +* Float Basics:: Representation and range of floating point. +* Predicates on Numbers:: Testing for numbers. +* Comparison of Numbers:: Equality and inequality predicates. +* Arithmetic Operations:: How to add, subtract, multiply and divide. +* Bitwise Operations:: Logical and, or, not, shifting. +* Numeric Conversions:: Converting float to integer and vice versa. +* Math Functions:: Trig, exponential and logarithmic functions. +* Random Numbers:: Obtaining random integers, predictable or not. + +Strings and Characters + +* String Basics:: Basic properties of strings and characters. +* Predicates for Strings:: Testing whether an object is a string or char. +* Creating Strings:: Functions to allocate new strings. +* Predicates for Characters:: Testing whether an object is a character. +* Character Codes:: Each character has an equivalent integer. +* Text Comparison:: Comparing characters or strings. +* String Conversion:: Converting characters or strings and vice versa. +* Modifying Strings:: Changing characters in a string. +* String Properties:: Additional information attached to strings. +* Formatting Strings:: `format': XEmacs's analog of `printf'. +* Character Case:: Case conversion functions. +* Char Tables:: Mapping from characters to Lisp objects. +* Case Tables:: Customizing case conversion. + +Lists + +* Cons Cells:: How lists are made out of cons cells. +* Lists as Boxes:: Graphical notation to explain lists. +* List-related Predicates:: Is this object a list? Comparing two lists. +* List Elements:: Extracting the pieces of a list. +* Building Lists:: Creating list structure. +* Modifying Lists:: Storing new pieces into an existing list. +* Sets And Lists:: A list can represent a finite mathematical set. +* Association Lists:: A list can represent a finite relation or mapping. +* Property Lists:: A different way to represent a finite mapping. +* Weak Lists:: A list with special garbage-collection behavior. + +Modifying Existing List Structure + +* Setcar:: Replacing an element in a list. +* Setcdr:: Replacing part of the list backbone. + This can be used to remove or add elements. +* Rearrangement:: Reordering the elements in a list; combining lists. + +Sequences, Arrays, and Vectors + +* Sequence Functions:: Functions that accept any kind of sequence. +* Arrays:: Characteristics of arrays in XEmacs Lisp. +* Array Functions:: Functions specifically for arrays. +* Vectors:: Functions specifically for vectors. + +Symbols + +* Symbol Components:: Symbols have names, values, function definitions + and property lists. +* Definitions:: A definition says how a symbol will be used. +* Creating Symbols:: How symbols are kept unique. +* Symbol Properties:: Each symbol has a property list + for recording miscellaneous information. + +Evaluation + +* Intro Eval:: Evaluation in the scheme of things. +* Eval:: How to invoke the Lisp interpreter explicitly. +* Forms:: How various sorts of objects are evaluated. +* Quoting:: Avoiding evaluation (to put constants in + the program). + +Kinds of Forms + +* Self-Evaluating Forms:: Forms that evaluate to themselves. +* Symbol Forms:: Symbols evaluate as variables. +* Classifying Lists:: How to distinguish various sorts of list forms. +* Function Forms:: Forms that call functions. +* Macro Forms:: Forms that call macros. +* Special Forms:: ``Special forms'' are idiosyncratic primitives, + most of them extremely important. +* Autoloading:: Functions set up to load files + containing their real definitions. + +Control Structures + +* Sequencing:: Evaluation in textual order. +* Conditionals:: `if', `cond'. +* Combining Conditions:: `and', `or', `not'. +* Iteration:: `while' loops. +* Nonlocal Exits:: Jumping out of a sequence. + +Nonlocal Exits + +* Catch and Throw:: Nonlocal exits for the program's own purposes. +* Examples of Catch:: Showing how such nonlocal exits can be written. +* Errors:: How errors are signaled and handled. +* Cleanups:: Arranging to run a cleanup form if an + error happens. + +Errors + +* Signaling Errors:: How to report an error. +* Processing of Errors:: What XEmacs does when you report an error. +* Handling Errors:: How you can trap errors and continue execution. +* Error Symbols:: How errors are classified for trapping them. + +Variables + +* Global Variables:: Variable values that exist permanently, everywhere. +* Constant Variables:: Certain "variables" have values that never change. +* Local Variables:: Variable values that exist only temporarily. +* Void Variables:: Symbols that lack values. +* Defining Variables:: A definition says a symbol is used as a variable. +* Accessing Variables:: Examining values of variables whose names + are known only at run time. +* Setting Variables:: Storing new values in variables. +* Variable Scoping:: How Lisp chooses among local and global values. +* Buffer-Local Variables:: Variable values in effect only in one buffer. + +Scoping Rules for Variable Bindings + +* Scope:: Scope means where in the program a value + is visible. Comparison with other languages. +* Extent:: Extent means how long in time a value exists. +* Impl of Scope:: Two ways to implement dynamic scoping. +* Using Scoping:: How to use dynamic scoping carefully and + avoid problems. + +Buffer-Local Variables + +* Intro to Buffer-Local:: Introduction and concepts. +* Creating Buffer-Local:: Creating and destroying buffer-local bindings. +* Default Value:: The default value is seen in buffers + that don't have their own local values. + +Functions + +* What Is a Function:: Lisp functions vs primitives; terminology. +* Lambda Expressions:: How functions are expressed as Lisp objects. +* Function Names:: A symbol can serve as the name of a function. +* Defining Functions:: Lisp expressions for defining functions. +* Calling Functions:: How to use an existing function. +* Mapping Functions:: Applying a function to each element of a list, etc. +* Anonymous Functions:: Lambda-expressions are functions with no names. +* Function Cells:: Accessing or setting the function definition + of a symbol. +* Related Topics:: Cross-references to specific Lisp primitives + that have a special bearing on how + functions work. + +Lambda Expressions + +* Lambda Components:: The parts of a lambda expression. +* Simple Lambda:: A simple example. +* Argument List:: Details and special features of argument lists. +* Function Documentation:: How to put documentation in a function. + +Macros + +* Simple Macro:: A basic example. +* Expansion:: How, when and why macros are expanded. +* Compiling Macros:: How macros are expanded by the compiler. +* Defining Macros:: How to write a macro definition. +* Backquote:: Easier construction of list structure. +* Problems with Macros:: Don't evaluate the macro arguments too many times. + Don't hide the user's variables. + +Loading + +* How Programs Do Loading:: The `load' function and others. +* Autoload:: Setting up a function to autoload. +* Named Features:: Loading a library if it isn't already loaded. +* Repeated Loading:: Precautions about loading a file twice. + +Byte Compilation + +* Speed of Byte-Code:: An example of speedup from byte compilation. +* Compilation Functions:: Byte compilation functions. +* Docs and Compilation:: Dynamic loading of documentation strings. +* Dynamic Loading:: Dynamic loading of individual functions. +* Eval During Compile:: Code to be evaluated when you compile. +* Compiled-Function Objects:: The data type used for byte-compiled functions. +* Disassembly:: Disassembling byte-code; how to read byte-code. +* Different Behavior:: When compiled code gives different results. + +Debugging Lisp Programs + +* Debugger:: How the XEmacs Lisp debugger is implemented. +* Syntax Errors:: How to find syntax errors. +* Compilation Errors:: How to find errors that show up in + byte compilation. +* Edebug:: A source-level XEmacs Lisp debugger. + +The Lisp Debugger + +* Error Debugging:: Entering the debugger when an error happens. +* Function Debugging:: Entering it when a certain function is called. +* Explicit Debug:: Entering it at a certain point in the program. +* Using Debugger:: What the debugger does; what you see while in it. +* Debugger Commands:: Commands used while in the debugger. +* Invoking the Debugger:: How to call the function `debug'. +* Internals of Debugger:: Subroutines of the debugger, and global variables. + +Debugging Invalid Lisp Syntax + +* Excess Open:: How to find a spurious open paren or missing close. +* Excess Close:: How to find a spurious close paren or missing open. + +Reading and Printing Lisp Objects + +* Streams Intro:: Overview of streams, reading and printing. +* Input Streams:: Various data types that can be used as + input streams. +* Input Functions:: Functions to read Lisp objects from text. +* Output Streams:: Various data types that can be used as + output streams. +* Output Functions:: Functions to print Lisp objects as text. + +Minibuffers + +* Intro to Minibuffers:: Basic information about minibuffers. +* Text from Minibuffer:: How to read a straight text string. +* Object from Minibuffer:: How to read a Lisp object or expression. +* Completion:: How to invoke and customize completion. +* Yes-or-No Queries:: Asking a question with a simple answer. +* Minibuffer Misc:: Various customization hooks and variables. + +Completion + +* Basic Completion:: Low-level functions for completing strings. + (These are too low level to use the minibuffer.) +* Minibuffer Completion:: Invoking the minibuffer with completion. +* Completion Commands:: Minibuffer commands that do completion. +* High-Level Completion:: Convenient special cases of completion + (reading buffer name, file name, etc.) +* Reading File Names:: Using completion to read file names. +* Programmed Completion:: Finding the completions for a given file name. + +Command Loop + +* Command Overview:: How the command loop reads commands. +* Defining Commands:: Specifying how a function should read arguments. +* Interactive Call:: Calling a command, so that it will read arguments. +* Command Loop Info:: Variables set by the command loop for you to examine. +* Events:: What input looks like when you read it. +* Reading Input:: How to read input events from the keyboard or mouse. +* Waiting:: Waiting for user input or elapsed time. +* Quitting:: How C-g works. How to catch or defer quitting. +* Prefix Command Arguments:: How the commands to set prefix args work. +* Recursive Editing:: Entering a recursive edit, + and why you usually shouldn't. +* Disabling Commands:: How the command loop handles disabled commands. +* Command History:: How the command history is set up, and how accessed. +* Keyboard Macros:: How keyboard macros are implemented. + +Defining Commands + +* Using Interactive:: General rules for `interactive'. +* Interactive Codes:: The standard letter-codes for reading arguments + in various ways. +* Interactive Examples:: Examples of how to read interactive arguments. + +Events + +* Event Types:: Events come in different types. +* Event Contents:: What the contents of each event type are. +* Event Predicates:: Querying whether an event is of a + particular type. +* Accessing Mouse Event Positions:: + Determining where a mouse event occurred, + and over what. +* Accessing Other Event Info:: Accessing non-positional event info. +* Working With Events:: Creating, copying, and destroying events. +* Converting Events:: Converting between events, keys, and + characters. + +Accessing Mouse Event Positions + +* Frame-Level Event Position Info:: +* Window-Level Event Position Info:: +* Event Text Position Info:: +* Event Glyph Position Info:: +* Event Toolbar Position Info:: +* Other Event Position Info:: + +Reading Input + +* Key Sequence Input:: How to read one key sequence. +* Reading One Event:: How to read just one event. +* Dispatching an Event:: What to do with an event once it has been read. +* Quoted Character Input:: Asking the user to specify a character. +* Peeking and Discarding:: How to reread or throw away input events. + +Keymaps + +* Keymap Terminology:: Definitions of terms pertaining to keymaps. +* Format of Keymaps:: What a keymap looks like as a Lisp object. +* Creating Keymaps:: Functions to create and copy keymaps. +* Inheritance and Keymaps:: How one keymap can inherit the bindings + of another keymap. +* Key Sequences:: How to specify key sequences. +* Prefix Keys:: Defining a key with a keymap as its definition. +* Active Keymaps:: Each buffer has a local keymap + to override the standard (global) bindings. + Each minor mode can also override them. +* Key Lookup:: How extracting elements from keymaps works. +* Functions for Key Lookup:: How to request key lookup. +* Changing Key Bindings:: Redefining a key in a keymap. +* Key Binding Commands:: Interactive interfaces for redefining keys. +* Scanning Keymaps:: Looking through all keymaps, for printing help. +* Other Keymap Functions:: Miscellaneous keymap functions. + +Menus + +* Menu Format:: Format of a menu description. +* Menubar Format:: How to specify a menubar. +* Menubar:: Functions for controlling the menubar. +* Modifying Menus:: Modifying a menu description. +* Pop-Up Menus:: Functions for specifying pop-up menus. +* Menu Filters:: Filter functions for the default menubar. +* Buffers Menu:: The menu that displays the list of buffers. + +Dialog Boxes + +* Dialog Box Format:: +* Dialog Box Functions:: + +Toolbar + +* Toolbar Intro:: An introduction. +* Toolbar Descriptor Format:: How to create a toolbar. +* Specifying the Toolbar:: Setting a toolbar. +* Other Toolbar Variables:: Controlling the size of toolbars. + +Gutter + +Scrollbars + +Major and Minor Modes + +* Major Modes:: Defining major modes. +* Minor Modes:: Defining minor modes. +* Modeline Format:: Customizing the text that appears in the modeline. +* Hooks:: How to use hooks; how to write code that + provides hooks. + +Major Modes + +* Major Mode Conventions:: Coding conventions for keymaps, etc. +* Example Major Modes:: Text mode and Lisp modes. +* Auto Major Mode:: How XEmacs chooses the major mode automatically. +* Mode Help:: Finding out how to use a mode. + +Minor Modes + +* Minor Mode Conventions:: Tips for writing a minor mode. +* Keymaps and Minor Modes:: How a minor mode can have its own keymap. + +Modeline Format + +* Modeline Data:: The data structure that controls the modeline. +* Modeline Variables:: Variables used in that data structure. +* %-Constructs:: Putting information into a modeline. + +Documentation + +* Documentation Basics:: Good style for doc strings. + Where to put them. How XEmacs stores them. +* Accessing Documentation:: How Lisp programs can access doc strings. +* Keys in Documentation:: Substituting current key bindings. +* Describing Characters:: Making printable descriptions of + non-printing characters and key sequences. +* Help Functions:: Subroutines used by XEmacs help facilities. + +Files + +* Visiting Files:: Reading files into Emacs buffers for editing. +* Saving Buffers:: Writing changed buffers back into files. +* Reading from Files:: Reading files into other buffers. +* Writing to Files:: Writing new files from parts of buffers. +* File Locks:: Locking and unlocking files, to prevent + simultaneous editing by two people. +* Information about Files:: Testing existence, accessibility, size of files. +* Contents of Directories:: Getting a list of the files in a directory. +* Changing File Attributes:: Renaming files, changing protection, etc. +* File Names:: Decomposing and expanding file names. + +Visiting Files + +* Visiting Functions:: The usual interface functions for visiting. +* Subroutines of Visiting:: Lower-level subroutines that they use. + +Information about Files + +* Testing Accessibility:: Is a given file readable? Writable? +* Kinds of Files:: Is it a directory? A link? +* File Attributes:: How large is it? Any other names? Etc. + +File Names + +* File Name Components:: The directory part of a file name, and the rest. +* Directory Names:: A directory's name as a directory + is different from its name as a file. +* Relative File Names:: Some file names are relative to a + current directory. +* File Name Expansion:: Converting relative file names to absolute ones. +* Unique File Names:: Generating names for temporary files. +* File Name Completion:: Finding the completions for a given file name. + +Backups and Auto-Saving + +* Backup Files:: How backup files are made; how their names + are chosen. +* Auto-Saving:: How auto-save files are made; how their + names are chosen. +* Reverting:: `revert-buffer', and how to customize + what it does. + +Backup Files + +* Making Backups:: How XEmacs makes backup files, and when. +* Rename or Copy:: Two alternatives: renaming the old file + or copying it. +* Numbered Backups:: Keeping multiple backups for each source file. +* Backup Names:: How backup file names are computed; customization. + +Buffers + +* Buffer Basics:: What is a buffer? +* Buffer Names:: Accessing and changing buffer names. +* Buffer File Name:: The buffer file name indicates which file + is visited. +* Buffer Modification:: A buffer is "modified" if it needs to be saved. +* Modification Time:: Determining whether the visited file was changed + ``behind XEmacs's back''. +* Read Only Buffers:: Modifying text is not allowed in a + read-only buffer. +* The Buffer List:: How to look at all the existing buffers. +* Creating Buffers:: Functions that create buffers. +* Killing Buffers:: Buffers exist until explicitly killed. +* Current Buffer:: Designating a buffer as current + so primitives will access its contents. + +Windows + +* Basic Windows:: Basic information on using windows. +* Splitting Windows:: Splitting one window into two windows. +* Deleting Windows:: Deleting a window gives its space to other windows. +* Selecting Windows:: The selected window is the one that you edit in. +* Cyclic Window Ordering:: Moving around the existing windows. +* Buffers and Windows:: Each window displays the contents of a buffer. +* Displaying Buffers:: Higher-lever functions for displaying a buffer + and choosing a window for it. +* Window Point:: Each window has its own location of point. +* Window Start:: The display-start position controls which text + is on-screen in the window. +* Vertical Scrolling:: Moving text up and down in the window. +* Horizontal Scrolling:: Moving text sideways on the window. +* Size of Window:: Accessing the size of a window. +* Resizing Windows:: Changing the size of a window. +* Window Configurations:: Saving and restoring the state of the screen. + +Frames + +* Creating Frames:: Creating additional frames. +* Frame Properties:: Controlling frame size, position, font, etc. +* Frame Titles:: Automatic updating of frame titles. +* Deleting Frames:: Frames last until explicitly deleted. +* Finding All Frames:: How to examine all existing frames. +* Frames and Windows:: A frame contains windows; + display of text always works through windows. +* Minibuffers and Frames:: How a frame finds the minibuffer to use. +* Input Focus:: Specifying the selected frame. +* Visibility of Frames:: Frames may be visible or invisible, or icons. +* Raising and Lowering:: Raising a frame makes it hide other X windows; + lowering it makes the others hide them. +* Frame Hooks:: Hooks for customizing frame behavior. + +Positions + +* Point:: The special position where editing takes place. +* Motion:: Changing point. +* Excursions:: Temporary motion and buffer changes. +* Narrowing:: Restricting editing to a portion of the buffer. + +Motion + +* Character Motion:: Moving in terms of characters. +* Word Motion:: Moving in terms of words. +* Buffer End Motion:: Moving to the beginning or end of the buffer. +* Text Lines:: Moving in terms of lines of text. +* Screen Lines:: Moving in terms of lines as displayed. +* List Motion:: Moving by parsing lists and sexps. +* Skipping Characters:: Skipping characters belonging to a certain set. + +Markers + +* Overview of Markers:: The components of a marker, and how it relocates. +* Predicates on Markers:: Testing whether an object is a marker. +* Creating Markers:: Making empty markers or markers at certain places. +* Information from Markers:: Finding the marker's buffer or character + position. +* Changing Markers:: Moving the marker to a new buffer or position. +* The Mark:: How ``the mark'' is implemented with a marker. +* The Region:: How to access ``the region''. + +Text + +* Near Point:: Examining text in the vicinity of point. +* Buffer Contents:: Examining text in a general fashion. +* Comparing Text:: Comparing substrings of buffers. +* Insertion:: Adding new text to a buffer. +* Commands for Insertion:: User-level commands to insert text. +* Deletion:: Removing text from a buffer. +* User-Level Deletion:: User-level commands to delete text. +* The Kill Ring:: Where removed text sometimes is saved for later use. +* Undo:: Undoing changes to the text of a buffer. +* Maintaining Undo:: How to enable and disable undo information. + How to control how much information is kept. +* Filling:: Functions for explicit filling. +* Margins:: How to specify margins for filling commands. +* Auto Filling:: How auto-fill mode is implemented to break lines. +* Sorting:: Functions for sorting parts of the buffer. +* Columns:: Computing horizontal positions, and using them. +* Indentation:: Functions to insert or adjust indentation. +* Case Changes:: Case conversion of parts of the buffer. +* Text Properties:: Assigning Lisp property lists to text characters. +* Substitution:: Replacing a given character wherever it appears. +* Registers:: How registers are implemented. Accessing the text or + position stored in a register. +* Transposition:: Swapping two portions of a buffer. +* Change Hooks:: Supplying functions to be run when text is changed. + +The Kill Ring + +* Kill Ring Concepts:: What text looks like in the kill ring. +* Kill Functions:: Functions that kill text. +* Yank Commands:: Commands that access the kill ring. +* Low-Level Kill Ring:: Functions and variables for kill ring access. +* Internals of Kill Ring:: Variables that hold kill-ring data. + +Indentation + +* Primitive Indent:: Functions used to count and insert indentation. +* Mode-Specific Indent:: Customize indentation for different modes. +* Region Indent:: Indent all the lines in a region. +* Relative Indent:: Indent the current line based on previous lines. +* Indent Tabs:: Adjustable, typewriter-like tab stops. +* Motion by Indent:: Move to first non-blank character. + +Searching and Matching + +* String Search:: Search for an exact match. +* Regular Expressions:: Describing classes of strings. +* Regexp Search:: Searching for a match for a regexp. +* Match Data:: Finding out which part of the text matched + various parts of a regexp, after regexp search. +* Saving Match Data:: Saving and restoring this information. +* Standard Regexps:: Useful regexps for finding sentences, pages,... +* Searching and Case:: Case-independent or case-significant searching. + +Regular Expressions + +* Syntax of Regexps:: Rules for writing regular expressions. +* Regexp Example:: Illustrates regular expression syntax. + +Syntax Tables + +* Syntax Descriptors:: How characters are classified. +* Syntax Table Functions:: How to create, examine and alter syntax tables. +* Parsing Expressions:: Parsing balanced expressions + using the syntax table. +* Standard Syntax Tables:: Syntax tables used by various major modes. +* Syntax Table Internals:: How syntax table information is stored. + +Syntax Descriptors + +* Syntax Class Table:: Table of syntax classes. +* Syntax Flags:: Additional flags each character can have. + +Abbrevs And Abbrev Expansion + +* Abbrev Mode:: Setting up XEmacs for abbreviation. +* Tables: Abbrev Tables. Creating and working with abbrev tables. +* Defining Abbrevs:: Specifying abbreviations and their expansions. +* Files: Abbrev Files. Saving abbrevs in files. +* Expansion: Abbrev Expansion. Controlling expansion; expansion subroutines. +* Standard Abbrev Tables:: Abbrev tables used by various major modes. + +Extents + +* Intro to Extents:: Extents are regions over a buffer or string. +* Creating and Modifying Extents:: + Basic extent functions. +* Extent Endpoints:: Accessing and setting the bounds of an extent. +* Finding Extents:: Determining which extents are in an object. +* Mapping Over Extents:: More sophisticated functions for extent scanning. +* Extent Properties:: Extents have built-in and user-definable properties. +* Detached Extents:: Extents that are not in a buffer. +* Extent Parents:: Inheriting properties from another extent. +* Duplicable Extents:: Extents can be marked to be copied into strings. +* Extents and Events:: Extents can interact with the keyboard and mouse. +* Atomic Extents:: Treating a block of text as a single entity. + +Specifiers + +* Introduction to Specifiers:: Specifiers provide a clean way for + display and other properties to vary + (under user control) in a wide variety + of contexts. +* Specifiers In-Depth:: Gory details about specifier innards. +* Specifier Instancing:: Instancing means obtaining the ``value'' of + a specifier in a particular context. +* Specifier Types:: Specifiers come in different flavors. +* Adding Specifications:: Specifications control a specifier's ``value'' + by giving conditions under which a + particular value is valid. +* Retrieving Specifications:: Querying a specifier's specifications. +* Specifier Instancing Functions:: + Functions to instance a specifier. +* Specifier Examples:: Making all this stuff clearer. +* Creating Specifiers:: Creating specifiers for your own use. +* Specifier Validation Functions:: + Validating the components of a specifier. +* Other Specification Functions:: + Other ways of working with specifications. + +Faces and Window-System Objects + +* Faces:: Controlling the way text looks. +* Fonts:: Controlling the typeface of text. +* Colors:: Controlling the color of text and pixmaps. + +Faces + +* Merging Faces:: How XEmacs decides which face to use + for a character. +* Basic Face Functions:: How to define and examine faces. +* Face Properties:: How to access and modify a face's properties. +* Face Convenience Functions:: Convenience functions for accessing + particular properties of a face. +* Other Face Display Functions:: Other functions pertaining to how a + a face appears. + +Fonts + +* Font Specifiers:: Specifying how a font will appear. +* Font Instances:: What a font specifier gets instanced as. +* Font Instance Names:: The name of a font instance. +* Font Instance Size:: The size of a font instance. +* Font Instance Characteristics:: Display characteristics of font instances. +* Font Convenience Functions:: Convenience functions that automatically + instance and retrieve the properties + of a font specifier. + +Colors + +* Color Specifiers:: Specifying how a color will appear. +* Color Instances:: What a color specifier gets instanced as. +* Color Instance Properties:: Properties of color instances. +* Color Convenience Functions:: Convenience functions that automatically + instance and retrieve the properties + of a color specifier. + +Glyphs + +* Glyph Intro:: Glyphs are abstract image specifications. +* Images:: Specifying the appearance of glyphs. +* Using Glyphs:: Creating and displaying glyphs. +* Manipulating Glyphs:: Getting and setting glyph properties. +* Glyph Examples:: Examples of how to work with glyphs. + +Images + +* Image Specifiers:: Specifying an image's appearance. +* Image Instantiator Conversion:: Lazy realization of graphics. +* Image Instantiator Formats:: A catalog of image descriptors. +* Image Instances:: Classes of graphical objects. + +Image Instances + +* Image Instance Types:: Each image instances has a particular type. +* Image Instance Functions:: Functions for working with image instances. + +Using Glyphs + + +Image Instances + +* Image Instance Types:: Each image instances has a particular type. +* Image Instance Functions:: Functions for working with image instances. + +Using Glyphs + +* Creating Glyphs:: Creating new glyphs. +* Buffer Glyphs:: Annotations are glyphs that appear in a buffer. +* Redisplay Glyphs:: Glyphs controlling various redisplay functions. +* Frame Glyphs:: Displaying glyphs in GUI components of the frame. +* External Glyphs:: Icons and mouse pointers for the window system. +* Native GUI Widgets:: Complex active elements treated as a single glyph. +* Subwindows:: Externally-controlled subwindows in buffers. + +Native GUI Widgets + +* Introduction to Widgets:: Native widgets provide tight integration of + GUI features with the platform GUI. +* Lisp API to Native Widgets:: Native widgets are glyphs. +* Layouts:: Specifying composite widgets from Lisp. +* Primitive Widgets:: Catalogue of available native widgets. + +Manipulating Glyphs + +* Glyph Properties:: Accessing and modifying a glyph's properties. +* Glyph Convenience Functions:: Accessing particular properties of a glyph. +* Glyph Dimensions:: Determining the height, width, etc. of a glyph. +* Glyph Types:: Each glyph has a particular type. + +Annotations + +* Annotation Basics:: Introduction to annotations. +* Annotation Primitives:: Creating and deleting annotations. +* Annotation Properties:: Retrieving and changing the characteristics + of an annotation. +* Margin Primitives:: Controlling the size of the margins. +* Locating Annotations:: Looking for annotations in a buffer. +* Annotation Hooks:: Hooks called at certain times during an + annotation's lifetime. + +Hash Tables + +* Introduction to Hash Tables:: Hash tables are fast data structures for + implementing simple tables (i.e. finite + mappings from keys to values). +* Working With Hash Tables:: Hash table functions. +* Weak Hash Tables:: Hash tables with special garbage-collection + behavior. + +Range Tables + +* Introduction to Range Tables:: Range tables efficiently map ranges of + integers to values. +* Working With Range Tables:: Range table functions. + + +XEmacs Display + +* Refresh Screen:: Clearing the screen and redrawing everything on it. +* Truncation:: Folding or wrapping long text lines. +* The Echo Area:: Where messages are displayed. +* Selective Display:: Hiding part of the buffer text. +* Overlay Arrow:: Display of an arrow to indicate position. +* Temporary Displays:: Displays that go away automatically. +* Blinking:: How XEmacs shows the matching open parenthesis. +* Usual Display:: The usual conventions for displaying nonprinting chars. +* Display Tables:: How to specify other conventions. +* Beeping:: Audible signal to the user. + +Processes + +* Subprocess Creation:: Functions that start subprocesses. +* Synchronous Processes:: Details of using synchronous subprocesses. +* Asynchronous Processes:: Starting up an asynchronous subprocess. +* Deleting Processes:: Eliminating an asynchronous subprocess. +* Process Information:: Accessing run-status and other attributes. +* Input to Processes:: Sending input to an asynchronous subprocess. +* Signals to Processes:: Stopping, continuing or interrupting + an asynchronous subprocess. +* Output from Processes:: Collecting output from an asynchronous subprocess. +* Sentinels:: Sentinels run when process run-status changes. +* Network:: Opening network connections. + +Receiving Output from Processes + +* Process Buffers:: If no filter, output is put in a buffer. +* Filter Functions:: Filter functions accept output from the process. +* Accepting Output:: How to wait until process output arrives. + +Operating System Interface + +* Starting Up:: Customizing XEmacs start-up processing. +* Getting Out:: How exiting works (permanent or temporary). +* System Environment:: Distinguish the name and kind of system. +* Terminal Input:: Recording terminal input for debugging. +* Terminal Output:: Recording terminal output for debugging. +* Flow Control:: How to turn output flow control on or off. +* Batch Mode:: Running XEmacs without terminal interaction. + +Starting Up XEmacs + +* Start-up Summary:: Sequence of actions XEmacs performs at start-up. +* Init File:: Details on reading the init file (`.emacs'). +* Terminal-Specific:: How the terminal-specific Lisp file is read. +* Command Line Arguments:: How command line arguments are processed, + and how you can customize them. + +Getting out of XEmacs + +* Killing XEmacs:: Exiting XEmacs irreversibly. +* Suspending XEmacs:: Exiting XEmacs reversibly. + +X-Windows + +* X Selections:: Transferring text to and from other X clients. +* X Server:: Information about the X server connected to + a particular device. +* Resources:: Getting resource values from the server. +* Server Data:: Getting info about the X server. +* Grabs:: Restricting access to the server by other apps. +* X Miscellaneous:: Other X-specific functions and variables. + +ToolTalk Support + +* XEmacs ToolTalk API Summary:: +* Sending Messages:: +* Receiving Messages:: + +LDAP Support + +* Building XEmacs with LDAP support:: How to add LDAP support to XEmacs +* XEmacs LDAP API:: Lisp access to LDAP functions +* Syntax of Search Filters:: A brief summary of RFC 1558 + +XEmacs LDAP API + +* LDAP Variables:: Lisp variables related to LDAP +* The High-Level LDAP API:: High-level LDAP lisp functions +* The Low-Level LDAP API:: Low-level LDAP lisp primitives +* LDAP Internationalization:: I18n variables and functions + +The Low-Level LDAP API + +* The LDAP Lisp Object:: +* Opening and Closing a LDAP Connection:: +* Low-level Operations on a LDAP Server:: + +LDAP Internationalization + +* LDAP Internationalization Variables:: +* Encoder/Decoder Functions:: + +Internationalization + +* I18N Levels 1 and 2:: Support for different time, date, and currency formats. +* I18N Level 3:: Support for localized messages. +* I18N Level 4:: Support for Asian languages. + +MULE + +* Internationalization Terminology:: + Definition of various internationalization terms. +* Charsets:: Sets of related characters. +* MULE Characters:: Working with characters in XEmacs/MULE. +* Composite Characters:: Making new characters by overstriking other ones. +* ISO 2022:: An international standard for charsets and encodings. +* Coding Systems:: Ways of representing a string of chars using integers. +* CCL:: A special language for writing fast converters. +* Category Tables:: Subdividing charsets into groups. + +Tips + +* Style Tips:: Writing clean and robust programs. +* Compilation Tips:: Making compiled code run fast. +* Documentation Tips:: Writing readable documentation strings. +* Comment Tips:: Conventions for writing comments. +* Library Headers:: Standard headers for library packages. + +Building XEmacs and Object Allocation + +* Building XEmacs:: How to preload Lisp libraries into XEmacs. +* Pure Storage:: A kludge to make preloaded Lisp functions sharable. +* Garbage Collection:: Reclaiming space for Lisp objects no longer used. + + +File: lispref.info, Node: Copying, Next: Introduction, Prev: Top, Up: Top + +GNU GENERAL PUBLIC LICENSE +************************** + + Version 2, June 1991 + + Copyright (C) 1989, 1991 Free Software Foundation, Inc. + 675 Mass Ave, Cambridge, MA 02139, USA + + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + +Preamble +======== + +The licenses for most software are designed to take away your freedom +to share and change it. By contrast, the GNU General Public License is +intended to guarantee your freedom to share and change free +software--to make sure the software is free for all its users. This +General Public License applies to most of the Free Software +Foundation's software and to any other program whose authors commit to +using it. (Some other Free Software Foundation software is covered by +the GNU Library General Public License instead.) You can apply it to +your programs, too. + + When we speak of free software, we are referring to freedom, not +price. Our General Public Licenses are designed to make sure that you +have the freedom to distribute copies of free software (and charge for +this service if you wish), that you receive source code or can get it +if you want it, that you can change the software or use pieces of it in +new free programs; and that you know you can do these things. + + To protect your rights, we need to make restrictions that forbid +anyone to deny you these rights or to ask you to surrender the rights. +These restrictions translate to certain responsibilities for you if you +distribute copies of the software, or if you modify it. + + For example, if you distribute copies of such a program, whether +gratis or for a fee, you must give the recipients all the rights that +you have. You must make sure that they, too, receive or can get the +source code. And you must show them these terms so they know their +rights. + + We protect your rights with two steps: (1) copyright the software, +and (2) offer you this license which gives you legal permission to copy, +distribute and/or modify the software. + + Also, for each author's protection and ours, we want to make certain +that everyone understands that there is no warranty for this free +software. If the software is modified by someone else and passed on, we +want its recipients to know that what they have is not the original, so +that any problems introduced by others will not reflect on the original +authors' reputations. + + Finally, any free program is threatened constantly by software +patents. We wish to avoid the danger that redistributors of a free +program will individually obtain patent licenses, in effect making the +program proprietary. To prevent this, we have made it clear that any +patent must be licensed for everyone's free use or not licensed at all. + + The precise terms and conditions for copying, distribution and +modification follow. + + TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION + 0. This License applies to any program or other work which contains a + notice placed by the copyright holder saying it may be distributed + under the terms of this General Public License. The "Program", + below, refers to any such program or work, and a "work based on + the Program" means either the Program or any derivative work under + copyright law: that is to say, a work containing the Program or a + portion of it, either verbatim or with modifications and/or + translated into another language. (Hereinafter, translation is + included without limitation in the term "modification".) Each + licensee is addressed as "you". + + Activities other than copying, distribution and modification are + not covered by this License; they are outside its scope. The act + of running the Program is not restricted, and the output from the + Program is covered only if its contents constitute a work based on + the Program (independent of having been made by running the + Program). Whether that is true depends on what the Program does. + + 1. You may copy and distribute verbatim copies of the Program's + source code as you receive it, in any medium, provided that you + conspicuously and appropriately publish on each copy an appropriate + copyright notice and disclaimer of warranty; keep intact all the + notices that refer to this License and to the absence of any + warranty; and give any other recipients of the Program a copy of + this License along with the Program. + + You may charge a fee for the physical act of transferring a copy, + and you may at your option offer warranty protection in exchange + for a fee. + + 2. You may modify your copy or copies of the Program or any portion + of it, thus forming a work based on the Program, and copy and + distribute such modifications or work under the terms of Section 1 + above, provided that you also meet all of these conditions: + + a. You must cause the modified files to carry prominent notices + stating that you changed the files and the date of any change. + + b. You must cause any work that you distribute or publish, that + in whole or in part contains or is derived from the Program + or any part thereof, to be licensed as a whole at no charge + to all third parties under the terms of this License. + + c. If the modified program normally reads commands interactively + when run, you must cause it, when started running for such + interactive use in the most ordinary way, to print or display + an announcement including an appropriate copyright notice and + a notice that there is no warranty (or else, saying that you + provide a warranty) and that users may redistribute the + program under these conditions, and telling the user how to + view a copy of this License. (Exception: if the Program + itself is interactive but does not normally print such an + announcement, your work based on the Program is not required + to print an announcement.) + + These requirements apply to the modified work as a whole. If + identifiable sections of that work are not derived from the + Program, and can be reasonably considered independent and separate + works in themselves, then this License, and its terms, do not + apply to those sections when you distribute them as separate + works. But when you distribute the same sections as part of a + whole which is a work based on the Program, the distribution of + the whole must be on the terms of this License, whose permissions + for other licensees extend to the entire whole, and thus to each + and every part regardless of who wrote it. + + Thus, it is not the intent of this section to claim rights or + contest your rights to work written entirely by you; rather, the + intent is to exercise the right to control the distribution of + derivative or collective works based on the Program. + + In addition, mere aggregation of another work not based on the + Program with the Program (or with a work based on the Program) on + a volume of a storage or distribution medium does not bring the + other work under the scope of this License. + + 3. You may copy and distribute the Program (or a work based on it, + under Section 2) in object code or executable form under the terms + of Sections 1 and 2 above provided that you also do one of the + following: + + a. Accompany it with the complete corresponding machine-readable + source code, which must be distributed under the terms of + Sections 1 and 2 above on a medium customarily used for + software interchange; or, + + b. Accompany it with a written offer, valid for at least three + years, to give any third party, for a charge no more than your + cost of physically performing source distribution, a complete + machine-readable copy of the corresponding source code, to be + distributed under the terms of Sections 1 and 2 above on a + medium customarily used for software interchange; or, + + c. Accompany it with the information you received as to the offer + to distribute corresponding source code. (This alternative is + allowed only for noncommercial distribution and only if you + received the program in object code or executable form with + such an offer, in accord with Subsection b above.) + + The source code for a work means the preferred form of the work for + making modifications to it. For an executable work, complete + source code means all the source code for all modules it contains, + plus any associated interface definition files, plus the scripts + used to control compilation and installation of the executable. + However, as a special exception, the source code distributed need + not include anything that is normally distributed (in either + source or binary form) with the major components (compiler, + kernel, and so on) of the operating system on which the executable + runs, unless that component itself accompanies the executable. + + If distribution of executable or object code is made by offering + access to copy from a designated place, then offering equivalent + access to copy the source code from the same place counts as + distribution of the source code, even though third parties are not + compelled to copy the source along with the object code. + + 4. You may not copy, modify, sublicense, or distribute the Program + except as expressly provided under this License. Any attempt + otherwise to copy, modify, sublicense or distribute the Program is + void, and will automatically terminate your rights under this + License. However, parties who have received copies, or rights, + from you under this License will not have their licenses + terminated so long as such parties remain in full compliance. + + 5. You are not required to accept this License, since you have not + signed it. However, nothing else grants you permission to modify + or distribute the Program or its derivative works. These actions + are prohibited by law if you do not accept this License. + Therefore, by modifying or distributing the Program (or any work + based on the Program), you indicate your acceptance of this + License to do so, and all its terms and conditions for copying, + distributing or modifying the Program or works based on it. + + 6. Each time you redistribute the Program (or any work based on the + Program), the recipient automatically receives a license from the + original licensor to copy, distribute or modify the Program + subject to these terms and conditions. You may not impose any + further restrictions on the recipients' exercise of the rights + granted herein. You are not responsible for enforcing compliance + by third parties to this License. + + 7. If, as a consequence of a court judgment or allegation of patent + infringement or for any other reason (not limited to patent + issues), conditions are imposed on you (whether by court order, + agreement or otherwise) that contradict the conditions of this + License, they do not excuse you from the conditions of this + License. If you cannot distribute so as to satisfy simultaneously + your obligations under this License and any other pertinent + obligations, then as a consequence you may not distribute the + Program at all. For example, if a patent license would not permit + royalty-free redistribution of the Program by all those who + receive copies directly or indirectly through you, then the only + way you could satisfy both it and this License would be to refrain + entirely from distribution of the Program. + + If any portion of this section is held invalid or unenforceable + under any particular circumstance, the balance of the section is + intended to apply and the section as a whole is intended to apply + in other circumstances. + + It is not the purpose of this section to induce you to infringe any + patents or other property right claims or to contest validity of + any such claims; this section has the sole purpose of protecting + the integrity of the free software distribution system, which is + implemented by public license practices. Many people have made + generous contributions to the wide range of software distributed + through that system in reliance on consistent application of that + system; it is up to the author/donor to decide if he or she is + willing to distribute software through any other system and a + licensee cannot impose that choice. + + This section is intended to make thoroughly clear what is believed + to be a consequence of the rest of this License. + + 8. If the distribution and/or use of the Program is restricted in + certain countries either by patents or by copyrighted interfaces, + the original copyright holder who places the Program under this + License may add an explicit geographical distribution limitation + excluding those countries, so that distribution is permitted only + in or among countries not thus excluded. In such case, this + License incorporates the limitation as if written in the body of + this License. + + 9. The Free Software Foundation may publish revised and/or new + versions of the General Public License from time to time. Such + new versions will be similar in spirit to the present version, but + may differ in detail to address new problems or concerns. + + Each version is given a distinguishing version number. If the + Program specifies a version number of this License which applies + to it and "any later version", you have the option of following + the terms and conditions either of that version or of any later + version published by the Free Software Foundation. If the Program + does not specify a version number of this License, you may choose + any version ever published by the Free Software Foundation. + + 10. If you wish to incorporate parts of the Program into other free + programs whose distribution conditions are different, write to the + author to ask for permission. For software which is copyrighted + by the Free Software Foundation, write to the Free Software + Foundation; we sometimes make exceptions for this. Our decision + will be guided by the two goals of preserving the free status of + all derivatives of our free software and of promoting the sharing + and reuse of software generally. + + NO WARRANTY + 11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO + WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE + LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT + HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT + WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT + NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND + FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE + QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE + PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY + SERVICING, REPAIR OR CORRECTION. + + 12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN + WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY + MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE + LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, + INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR + INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF + DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU + OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY + OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN + ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. + + END OF TERMS AND CONDITIONS +How to Apply These Terms to Your New Programs +============================================= + +If you develop a new program, and you want it to be of the greatest +possible use to the public, the best way to achieve this is to make it +free software which everyone can redistribute and change under these +terms. + + To do so, attach the following notices to the program. It is safest +to attach them to the start of each source file to most effectively +convey the exclusion of warranty; and each file should have at least +the "copyright" line and a pointer to where the full notice is found. + + ONE LINE TO GIVE THE PROGRAM'S NAME AND AN IDEA OF WHAT IT DOES. + Copyright (C) 19YY NAME OF AUTHOR + + This program 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 2 + of the License, or (at your option) any later version. + + This program 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 this program; if not, write to the Free Software + Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. + + Also add information on how to contact you by electronic and paper +mail. + + If the program is interactive, make it output a short notice like +this when it starts in an interactive mode: + + Gnomovision version 69, Copyright (C) 19YY NAME OF AUTHOR + Gnomovision comes with ABSOLUTELY NO WARRANTY; for details + type `show w'. This is free software, and you are welcome + to redistribute it under certain conditions; type `show c' + for details. + + The hypothetical commands `show w' and `show c' should show the +appropriate parts of the General Public License. Of course, the +commands you use may be called something other than `show w' and `show +c'; they could even be mouse-clicks or menu items--whatever suits your +program. + + You should also get your employer (if you work as a programmer) or +your school, if any, to sign a "copyright disclaimer" for the program, +if necessary. Here is a sample; alter the names: + + Yoyodyne, Inc., hereby disclaims all copyright + interest in the program `Gnomovision' + (which makes passes at compilers) written + by James Hacker. + + SIGNATURE OF TY COON, 1 April 1989 + Ty Coon, President of Vice + + This General Public License does not permit incorporating your +program into proprietary programs. If your program is a subroutine +library, you may consider it more useful to permit linking proprietary +applications with the library. If this is what you want to do, use the +GNU Library General Public License instead of this License. + + +File: lispref.info, Node: Introduction, Next: Packaging, Prev: Copying, Up: Top + +1 Introduction +************** + +Most of the XEmacs text editor is written in the programming language +called XEmacs Lisp. You can write new code in XEmacs Lisp and install +it as an extension to the editor. However, XEmacs Lisp is more than a +mere "extension language"; it is a full computer programming language +in its own right. You can use it as you would any other programming +language. + + Because XEmacs Lisp is designed for use in an editor, it has special +features for scanning and parsing text as well as features for handling +files, buffers, displays, subprocesses, and so on. XEmacs Lisp is +closely integrated with the editing facilities; thus, editing commands +are functions that can also conveniently be called from Lisp programs, +and parameters for customization are ordinary Lisp variables. + + This manual describes XEmacs Lisp, presuming considerable familiarity +with the use of XEmacs for editing. (See `The XEmacs Reference +Manual', for this basic information.) Generally speaking, the earlier +chapters describe features of XEmacs Lisp that have counterparts in many +programming languages, and later chapters describe features that are +peculiar to XEmacs Lisp or relate specifically to editing. + + This is edition 3.3. + +* Menu: + +* Caveats:: Flaws and a request for help. +* Lisp History:: XEmacs Lisp is descended from Maclisp. +* Conventions:: How the manual is formatted. +* Acknowledgements:: The authors, editors, and sponsors of this manual. + + +File: lispref.info, Node: Caveats, Next: Lisp History, Up: Introduction + +1.1 Caveats +=========== + +This manual has gone through numerous drafts. It is nearly complete +but not flawless. There are a few topics that are not covered, either +because we consider them secondary (such as most of the individual +modes) or because they are yet to be written. Because we are not able +to deal with them completely, we have left out several parts +intentionally. + + The manual should be fully correct in what it does cover, and it is +therefore open to criticism on anything it says--from specific examples +and descriptive text, to the ordering of chapters and sections. If +something is confusing, or you find that you have to look at the sources +or experiment to learn something not covered in the manual, then perhaps +the manual should be fixed. Please let us know. + + As you use this manual, we ask that you send corrections as soon as +you find them. If you think of a simple, real life example for a +function or group of functions, please make an effort to write it up +and send it in. Please reference any comments to the node name and +function or variable name, as appropriate. Also state the number of +the edition which you are criticizing. + + This manual was originally written for FSF Emacs 19 and was updated +by Ben Wing (ben@xemacs.org) for Lucid Emacs 19.10 and later for XEmacs +19.12, 19.13, 19.14, and 20.0. It was further updated by the XEmacs +Development Team for 19.15 and 20.1. Please send comments and +corrections relating to XEmacs-specific portions of this manual to + xemacs@xemacs.org + + or post to the newsgroup + comp.emacs.xemacs + + + -Ben Wing + + +File: lispref.info, Node: Lisp History, Next: Conventions, Prev: Caveats, Up: Introduction + +1.2 Lisp History +================ + +Lisp (LISt Processing language) was first developed in the late 1950's +at the Massachusetts Institute of Technology for research in artificial +intelligence. The great power of the Lisp language makes it superior +for other purposes as well, such as writing editing commands. + + Dozens of Lisp implementations have been built over the years, each +with its own idiosyncrasies. Many of them were inspired by Maclisp, +which was written in the 1960's at MIT's Project MAC. Eventually the +implementors of the descendants of Maclisp came together and developed a +standard for Lisp systems, called Common Lisp. + + XEmacs Lisp is largely inspired by Maclisp, and a little by Common +Lisp. If you know Common Lisp, you will notice many similarities. +However, many of the features of Common Lisp have been omitted or +simplified in order to reduce the memory requirements of XEmacs. +Sometimes the simplifications are so drastic that a Common Lisp user +might be very confused. We will occasionally point out how XEmacs Lisp +differs from Common Lisp. If you don't know Common Lisp, don't worry +about it; this manual is self-contained. + + +File: lispref.info, Node: Conventions, Next: Acknowledgements, Prev: Lisp History, Up: Introduction + +1.3 Conventions +=============== + +This section explains the notational conventions that are used in this +manual. You may want to skip this section and refer back to it later. + +* Menu: + +* Some Terms:: Explanation of terms we use in this manual. +* nil and t:: How the symbols `nil' and `t' are used. +* Evaluation Notation:: The format we use for examples of evaluation. +* Printing Notation:: The format we use for examples that print output. +* Error Messages:: The format we use for examples of errors. +* Buffer Text Notation:: The format we use for buffer contents in examples. +* Format of Descriptions:: Notation for describing functions, variables, etc. + + +File: lispref.info, Node: Some Terms, Next: nil and t, Up: Conventions + +1.3.1 Some Terms +---------------- + +Throughout this manual, the phrases "the Lisp reader" and "the Lisp +printer" are used to refer to those routines in Lisp that convert +textual representations of Lisp objects into actual Lisp objects, and +vice versa. *Note Printed Representation::, for more details. You, the +person reading this manual, are thought of as "the programmer" and are +addressed as "you". "The user" is the person who uses Lisp programs, +including those you write. + + Examples of Lisp code appear in this font or form: `(list 1 2 3)'. +Names that represent arguments or metasyntactic variables appear in +this font or form: FIRST-NUMBER. + + +File: lispref.info, Node: nil and t, Next: Evaluation Notation, Prev: Some Terms, Up: Conventions + +1.3.2 `nil' and `t' +------------------- + +In Lisp, the symbol `nil' has three separate meanings: it is a symbol +with the name `nil'; it is the logical truth value FALSE; and it is the +empty list--the list of zero elements. When used as a variable, `nil' +always has the value `nil'. + + As far as the Lisp reader is concerned, `()' and `nil' are +identical: they stand for the same object, the symbol `nil'. The +different ways of writing the symbol are intended entirely for human +readers. After the Lisp reader has read either `()' or `nil', there is +no way to determine which representation was actually written by the +programmer. + + In this manual, we use `()' when we wish to emphasize that it means +the empty list, and we use `nil' when we wish to emphasize that it +means the truth value FALSE. That is a good convention to use in Lisp +programs also. + + (cons 'foo ()) ; Emphasize the empty list + (not nil) ; Emphasize the truth value FALSE + + In contexts where a truth value is expected, any non-`nil' value is +considered to be TRUE. However, `t' is the preferred way to represent +the truth value TRUE. When you need to choose a value which represents +TRUE, and there is no other basis for choosing, use `t'. The symbol +`t' always has value `t'. + + In XEmacs Lisp, `nil' and `t' are special symbols that always +evaluate to themselves. This is so that you do not need to quote them +to use them as constants in a program. An attempt to change their +values results in a `setting-constant' error. *Note Accessing +Variables::. + + +File: lispref.info, Node: Evaluation Notation, Next: Printing Notation, Prev: nil and t, Up: Conventions + +1.3.3 Evaluation Notation +------------------------- + +A Lisp expression that you can evaluate is called a "form". Evaluating +a form always produces a result, which is a Lisp object. In the +examples in this manual, this is indicated with `=>': + + (car '(1 2)) + => 1 + +You can read this as "`(car '(1 2))' evaluates to 1". + + When a form is a macro call, it expands into a new form for Lisp to +evaluate. We show the result of the expansion with `==>'. We may or +may not show the actual result of the evaluation of the expanded form. + + (news-cadr '(a b c)) + ==> (car (cdr '(a b c))) + => b + + Sometimes to help describe one form we show another form that +produces identical results. The exact equivalence of two forms is +indicated with `=='. + + (cons 'a nil) == (list 'a) + + +File: lispref.info, Node: Printing Notation, Next: Error Messages, Prev: Evaluation Notation, Up: Conventions + +1.3.4 Printing Notation +----------------------- + +Many of the examples in this manual print text when they are evaluated. +If you execute example code in a Lisp Interaction buffer (such as the +buffer `*scratch*'), the printed text is inserted into the buffer. If +you execute the example by other means (such as by evaluating the +function `eval-region'), the printed text is displayed in the echo +area. You should be aware that text displayed in the echo area is +truncated to a single line. + + Examples in this manual indicate printed text with `-|', +irrespective of where that text goes. The value returned by evaluating +the form (here `bar') follows on a separate line. + + (progn (print 'foo) (print 'bar)) + -| foo + -| bar + => bar + + +File: lispref.info, Node: Error Messages, Next: Buffer Text Notation, Prev: Printing Notation, Up: Conventions + +1.3.5 Error Messages +-------------------- + +Some examples signal errors. This normally displays an error message +in the echo area. We show the error message on a line starting with +`error-->'. Note that `error-->' itself does not appear in the echo +area. + + (+ 23 'x) + error--> Wrong type argument: integer-or-marker-p, x + + +File: lispref.info, Node: Buffer Text Notation, Next: Format of Descriptions, Prev: Error Messages, Up: Conventions + +1.3.6 Buffer Text Notation +-------------------------- + +Some examples show modifications to text in a buffer, with "before" and +"after" versions of the text. These examples show the contents of the +buffer in question between two lines of dashes containing the buffer +name. In addition, `-!-' indicates the location of point. (The symbol +for point, of course, is not part of the text in the buffer; it +indicates the place _between_ two characters where point is located.) + + ---------- Buffer: foo ---------- + This is the -!-contents of foo. + ---------- Buffer: foo ---------- + + (insert "changed ") + => nil + ---------- Buffer: foo ---------- + This is the changed -!-contents of foo. + ---------- Buffer: foo ---------- + + +File: lispref.info, Node: Format of Descriptions, Prev: Buffer Text Notation, Up: Conventions + +1.3.7 Format of Descriptions +---------------------------- + +Functions, variables, macros, commands, user options, and special forms +are described in this manual in a uniform format. The first line of a +description contains the name of the item followed by its arguments, if +any. The category--function, variable, or whatever--appears at the +beginning of the line. The description follows on succeeding lines, +sometimes with examples. + +* Menu: + +* A Sample Function Description:: A description of an imaginary + function, `foo'. +* A Sample Variable Description:: A description of an imaginary + variable, + `electric-future-map'. + + +File: lispref.info, Node: A Sample Function Description, Next: A Sample Variable Description, Up: Format of Descriptions + +1.3.7.1 A Sample Function Description +..................................... + +In a function description, the name of the function being described +appears first. It is followed on the same line by a list of parameters. +The names used for the parameters are also used in the body of the +description. + + The appearance of the keyword `&optional' in the parameter list +indicates that the arguments for subsequent parameters may be omitted +(omitted parameters default to `nil'). Do not write `&optional' when +you call the function. + + The keyword `&rest' (which will always be followed by a single +parameter) indicates that any number of arguments can follow. The value +of the single following parameter will be a list of all these arguments. +Do not write `&rest' when you call the function. + + Here is a description of an imaginary function `foo': + + -- Function: foo integer1 &optional integer2 &rest integers + The function `foo' subtracts INTEGER1 from INTEGER2, then adds all + the rest of the arguments to the result. If INTEGER2 is not + supplied, then the number 19 is used by default. + + (foo 1 5 3 9) + => 16 + (foo 5) + => 14 + + More generally, + + (foo W X Y...) + == + (+ (- X W) Y...) + + Any parameter whose name contains the name of a type (e.g., INTEGER, +INTEGER1 or BUFFER) is expected to be of that type. A plural of a type +(such as BUFFERS) often means a list of objects of that type. +Parameters named OBJECT may be of any type. (*Note Lisp Data Types::, +for a list of XEmacs object types.) Parameters with other sorts of +names (e.g., NEW-FILE) are discussed specifically in the description of +the function. In some sections, features common to parameters of +several functions are described at the beginning. + + *Note Lambda Expressions::, for a more complete description of +optional and rest arguments. + + Command, macro, and special form descriptions have the same format, +but the word `Function' is replaced by `Command', `Macro', or `Special +Form', respectively. Commands are simply functions that may be called +interactively; macros process their arguments differently from functions +(the arguments are not evaluated), but are presented the same way. + + Special form descriptions use a more complex notation to specify +optional and repeated parameters because they can break the argument +list down into separate arguments in more complicated ways. +``[OPTIONAL-ARG]'' means that OPTIONAL-ARG is optional and +`REPEATED-ARGS...' stands for zero or more arguments. Parentheses are +used when several arguments are grouped into additional levels of list +structure. Here is an example: + + -- Special Form: count-loop (VAR [FROM TO [INC]]) BODY... + This imaginary special form implements a loop that executes the + BODY forms and then increments the variable VAR on each iteration. + On the first iteration, the variable has the value FROM; on + subsequent iterations, it is incremented by 1 (or by INC if that + is given). The loop exits before executing BODY if VAR equals TO. + Here is an example: + + (count-loop (i 0 10) + (prin1 i) (princ " ") + (prin1 (aref vector i)) (terpri)) + + If FROM and TO are omitted, then VAR is bound to `nil' before the + loop begins, and the loop exits if VAR is non-`nil' at the + beginning of an iteration. Here is an example: + + (count-loop (done) + (if (pending) + (fixit) + (setq done t))) + + In this special form, the arguments FROM and TO are optional, but + must both be present or both absent. If they are present, INC may + optionally be specified as well. These arguments are grouped with + the argument VAR into a list, to distinguish them from BODY, which + includes all remaining elements of the form. + + +File: lispref.info, Node: A Sample Variable Description, Prev: A Sample Function Description, Up: Format of Descriptions + +1.3.7.2 A Sample Variable Description +..................................... + +A "variable" is a name that can hold a value. Although any variable +can be set by the user, certain variables that exist specifically so +that users can change them are called "user options". Ordinary +variables and user options are described using a format like that for +functions except that there are no arguments. + + Here is a description of the imaginary `electric-future-map' +variable. + + -- Variable: electric-future-map + The value of this variable is a full keymap used by Electric + Command Future mode. The functions in this map allow you to edit + commands you have not yet thought about executing. + + User option descriptions have the same format, but `Variable' is +replaced by `User Option'. + + +File: lispref.info, Node: Acknowledgements, Prev: Conventions, Up: Introduction + +1.4 Acknowledgements +==================== + +This manual was based on the GNU Emacs Lisp Reference Manual, version +2.4, written by Robert Krawitz, Bil Lewis, Dan LaLiberte, Richard M. +Stallman and Chris Welty, the volunteers of the GNU manual group, in an +effort extending over several years. Robert J. Chassell helped to +review and edit the manual, with the support of the Defense Advanced +Research Projects Agency, ARPA Order 6082, arranged by Warren A. Hunt, +Jr. of Computational Logic, Inc. + + Ben Wing adapted this manual for XEmacs 19.14 and 20.0, and earlier +for Lucid Emacs 19.10, XEmacs 19.12, and XEmacs 19.13. He is the sole +author of many of the manual sections, in particular the XEmacs-specific +sections: events, faces, extents, glyphs, specifiers, toolbar, menubars, +scrollbars, dialog boxes, devices, consoles, hash tables, range tables, +char tables, databases, and others. The section on annotations was +originally written by Chuck Thompson. Corrections to v3.1 and later +were done by Martin Buchholz, Steve Baur, and Hrvoje Niksic. + + Corrections to the original GNU Emacs Lisp Reference Manual were +supplied by Karl Berry, Jim Blandy, Bard Bloom, Stephane Boucher, David +Boyes, Alan Carroll, Richard Davis, Lawrence R. Dodd, Peter Doornbosch, +David A. Duff, Chris Eich, Beverly Erlebacher, David Eckelkamp, Ralf +Fassel, Eirik Fuller, Stephen Gildea, Bob Glickstein, Eric Hanchrow, +George Hartzell, Nathan Hess, Masayuki Ida, Dan Jacobson, Jak Kirman, +Bob Knighten, Frederick M. Korz, Joe Lammens, Glenn M. Lewis, K. Richard +Magill, Brian Marick, Roland McGrath, Skip Montanaro, John Gardiner +Myers, Thomas A. Peterson, Francesco Potorti, Friedrich Pukelsheim, +Arnold D. Robbins, Raul Rockwell, Per Starback, Shinichirou Sugou, Kimmo +Suominen, Edward Tharp, Bill Trost, Rickard Westman, Jean White, Matthew +Wilding, Carl Witty, Dale Worley, Rusty Wright, and David D. Zuhn. + + +File: lispref.info, Node: Packaging, Next: Lisp Data Types, Prev: Introduction, Up: Top + +2 The XEmacs Packaging System +***************************** + +The XEmacs distribution, starting with version 21, comes only with a +very basic set of built-in modes and libraries. Most of the libraries +that were part of the distribution of earlier versions of XEmacs are now +available separately. The user as well as the system administrator can +choose which packages to install; the actual installation process is +easy. This gives an installer the ability to tailor an XEmacs +installation for local needs with safe removal of unnecessary code. + + This chapter describes how to package Lisp libraries for use with the +XEmacs Packaging System. + + _Please note carefully_ that the term "package" as used in XEmacs +refers to an aggregation of Lisp code and/or data distributed as a +unit. It does not, as it does in many Lisps, refer to a way of +creating separate name spaces. XEmacs has no facility for providing +separate name spaces. (If we ever do get separate name spaces, we'll +probably regret overloading the nomenclature in this way, but it's +become established.) + +* Menu: + +Introduction: +* Package Overview:: Lisp Libraries and Packages. + +Packaging Lisp Libraries: +* Package Terminology:: Basic stuff. +* Building Packages:: Turn packaged source into a tarball. +* Makefile Targets:: Package `Makefile' targets +* Local.rules File:: Tell the XEmacs Packaging System about your host. +* Creating Packages:: Tell the XEmacs Packaging System about your package. +* Documenting Packages:: Explain your package to users and hackers. + +Internals and Package Release Engineering: +* Issues:: + + +File: lispref.info, Node: Package Overview, Next: Package Terminology, Up: Packaging + +3 An overview of the XEmacs Packaging System +******************************************** + +The XEmacs Packaging System is a system for administering the +installation, upgrade, and removal of Lisp libraries. For the end +user, it provides facilities for determining availability of packages +and which versions at remote sites. It will download and automatically +install a package, ensuring that any old files from previous versions +of the package are removed first. By providing a standard set of +hierarchies for installation, it makes configuration of XEmacs simpler. +Furthermore, packages normally provide ancillary auto-autoloads and +custom-loads libraries, which are automatically detected and loaded by +XEmacs upon startup. This means that once installed, all facilities of +package, including autoloading the library upon invocation of a command +provided by the library and convenient configuration and customization, +are automatically available to the user. There is no need to add +autoloads or keybindings to in the init file, and structured +configuration of the package is available through the Customize system +even before the libraries are loaded. + + All of this convenience comes at a cost. The cost of administration +at the package level is negligible compared to the benefits, of course. +However, the requirement that XEmacs find and load auto-autoloads and +custom-loads libraries comes at a fairly large cost in startup time. In +order to reduce this cost, XEmacs imposes fairly strict conditions on +the structure of an installed package. + + Meeting these requirements, as well as simply providing the +auto-autoloads and the information about availability and so on does +impose some costs on the library maintainer. The XEmacs Packaging +System also provides structure and utilities to the library maintainer +to make these tasks easier. This manual documents the requirements and +the tools that the XEmacs Packaging System provides to ensure that a +package satisfies them. + +* Menu: + +* The User View:: +* The Library Maintainer View:: +* The Package Release Engineer View:: + + +File: lispref.info, Node: The User View, Next: The Library Maintainer View, Up: Package Overview + +3.1 The User View +================= + +*N.B.* Much of the discussion in this section undoubtedly belongs +elsewhere, *Note Packages: (xemacs)Packages. + + From the user's point of view, an XEmacs binary package is simply a +standard tarball (usually gzipped) containing Lisp sources, compiled +Lisp, documentation, and possibly data files or supporting executables. +The tarball is unpacked using standard tools such as GNU tar and gzip. +The package system does impose certain requirements for automatic +configuration to work. + + Here the main consideration is that the tarball "expects" to be +unpacked from the top of a package hierarchy. A "package hierarchy" is +basically an image of a classic Emacs "run-in-place" tree, with `lisp', +`etc', `info', `man', `lib-src', and `pkginfo' subdirectories of the +top. The `pkginfo' subdirectory is for use by the XEmacs Packaging +System administration tools, and currently contains a +`MANIFEST.PACKAGE-NAME' file for each package to ensure that no cruft +remains when a package is removed or updated. The `lisp', `etc', and +`lib-src' subdirectories are further subdivided, with a subdirectory +for each package. The `info' directory obeys the usual conventions. +_I.e._, the `info' directory is flat with a(n) (optional) `dir' file +and one (set of) info file(s) per package. The `man' subdirectory +typically contains documentation sources, separated by package. (It +does not contain `man(1)' pages, as Emacs provides very few of them.) + + There are several standard package hierarchies, and administrators +can configure others at build time, while users can configure others at +run time. The standard system hierarchies are all subdirectories of an +XEmacs installation root, typically `/usr/local/lib/xemacs/'. These +are the `xemacs-packages', `mule-packages', `infodock-packages', and +`site-packages' hierarchies. Each has the structure described above, +but the purposes differ. The `xemacs-packages' is the normal place for +installing "official" packages and many third-party libraries. +Unfortunately, it is not yet quite possible to read libraries +containing international characters with a non-Mule XEmacs, so such +libraries are sequestered in the `mule-packages' hierarchy. Some +packages are compatible only with the Infodock development environment, +and they will be installed in the `infodock-packages' hierarchy. The +`site-packages' hierarchy is for packages not distributed by +XEmacs.org, typically locally developed. + + Packages are in principle supposed to be XEmacs version-independent, +but if such dependencies are unavoidable, additional standard package +hierarchies may be installed under version directories, _e.g._ +`/usr/local/lib/xemacs-21.4.6/'. + + Users who do not have sufficient privilege to install packages in the +system hierarchies may install package hierarchies under `~/.xemacs'. +At present only the `xemacs-packages', `mule-packages', and +`site-packages' hierarchies are supported, but it might make sense to +extend this to support `infodock-packages' hierarchies in the future. + + The package hierarchies are not searched directly for libraries to be +loaded; this would be very costly. Instead, the hierarchies are ordered +according to certain rules, and searched for package lisp directories at +invocation. These directories are added to the general `load-path'. +As usual, it is `load-path' that is searched at run-time. This +approach is somewhat costly at initialization, but results in a very +"clean" `load-path'. + + The order of search can be changed at build time by specifying the +`--package-path' option to `configure', or at run-time by specifying +the `EMACSPACKAGEPATH' environment variable. *Note Packages: +(xemacs)Packages. + + The default order of search is hierarchically determined. First, the +roots are ordered. The "early" roots are the user-specific roots, +typically `~/.xemacs'. The "late" roots are the system roots, +typically `/usr/local/lib/xemacs-21.4.6' and `/usr/local/lib/xemacs', +in that order. All hierarchies for a given root are searched for +package Lisp directories, which are appended to `load-path' in the +order found. Then the search proceeds to the next root, whose results +will be appended to the `load-path' generated by previous roots. + + Second, the hierarchies below each root are searched in the order +`site-packages', `infodock-packages', `mule-packages', then +`xemacs-packages'. + + In each hierarchy there should be a `lisp' subdirectory, containing +directories named for the packages. Each package's Lisp libraries thus +are contained in a directory of the form ROOT/HIERARCHY/lisp/PACKAGE/. + + With such a complex search algorithm, the possibility of libraries +being shadowed by another library with the same name is quite real. +There are two considerations here. First, every XEmacs package +contains certain libraries with constant names. These are + +`_pkg.el' + Lisp code to inform the package administration system about the + package + +`auto-autoloads.el' + Lisp code to set up autoloaded functions and variables that may be + needed at load time + +`custom-load.el' + definitions of configuration variables for use with the Customize + system. + + They are special-cased, because the way they are used prevents +shadowing from being an issue. + + Second, it is possible that multiple copies of some library, or +different libraries with the same name, are installed in various places +in the hierarchies. To detect such shadows, use +`list-load-path-shadows'. + + Finally, note that most basic Emacs functionality, including most of +the Lisp API, is implemented in Lisp libraries. Because they use +internal reserved APIs that are subject to change according the needs +of the developers, these libraries are distributed with the XEmacs +binary, and are called "core Lisp libraries". Most core Lisp libraries +are "preloaded" into the Emacs binary and in normal usage are never +explicitly loaded. However, they can be explicitly loaded, and if so +they are searched on `load-path'. Furthermore, functions such as +`locate-library' will also search on the `load-path'. The searching +takes place under somewhat different rules from those used for packaged +Lisp. It is probably easiest to think of the package hierarchy +searching algorithm as receiving a `load-path' initialized to the core +Lisp directories. + + +File: lispref.info, Node: The Library Maintainer View, Next: The Package Release Engineer View, Prev: The User View, Up: Package Overview + +3.2 The Library Maintainer View +=============================== + +From the library maintainer's viewpoint, the advantages to the XEmacs +Packaging System stem from the convenience to the user of installation +and upgrade. Since an installed package automatically registers its +entry points via autoload and its configuration variables with the +Customize system, configuration FAQs are reduced. When it's easy to +upgrade, users learn to try `Tools | Packages | Update Installed +Packages' before posting a FAQ whose answer is "long since fixed, +please upgrade." + + This comes at some cost, as the library maintainer needs to arrange +that the package be installed in a directory structure that satisfies +the requirements of the XEmacs Packaging System. Autoload cookies and +defcustoms must also be added to existing libraries. The XEmacs +Packaging System provides infrastructure to assure that all of these +annoyances need only be dealt with once. The autoload cookies and +defcustoms are beyond the scope of this chapter, but most maintainers +of modern packages are already familiar with these mechanisms. + + The XEmacs Packaging System may be divided into the "infrastructure" +common to all packages, and the package-specific "control files". The +infrastructure supports global builds, installation, and generation of +the "sumo" bundles of packages, as well as generation of individual +packages. The package control files describe the structure of the +package's source tree and provide administrative information. + +* Menu: + +* Infrastructure:: Global Makefiles and common rules. +* Control Files:: Package-specific Makefiles and administrative files. +* Obtaining:: Obtaining the XEmacs Packaging System and required utilities. + + +File: lispref.info, Node: Infrastructure, Next: Control Files, Up: The Library Maintainer View + +3.2.1 Infrastructure +-------------------- + +In order to get the greatest benefit from the XEmacs Packaging System, +a library maintainer should place the package sources in an appropriate +place in the XEmacs source package hierarchy, and arrange to have the +source package imported into the XEmacs CVS repository. (We realize +that the latter requirement can be quite burdensome. We are working on +ways to remove this requirement, but for the present it remains +necessary.) The library maintainer must also keep sources for any +packages his/her package requires. This requirement is somewhat +burdensome, but unlikely to be relaxed because of the implementation of +compilation of macros in Emacs Lisp. Macros cannot be called by +compiled Lisp (the macro expansion, which is always known at compile +time, is inlined), so the source of the macro must be loaded before +compiling the called function. + + The source package hierarchy may be rooted anywhere. The CVS module +is called "packages," so we will refer to the top directory of the +source package hierarchy as "the `packages' directory." The `packages' +directory contains two source subdirectories, `xemacs-packages' and +`mule-packages' (for convenience in segregating the packages which +depend on Mule, as they will cause load-time errors in a non-Mule +XEmacs). Each subdirectory contains many package source directories, +whose internal structure is not specified. That structure is left up +to the convenience of the library maintainers. The requirements on the +top directory of an individual package source tree are given below, +*Note Control Files::. + + The `packages' directory contains some auxiliary Lisp libraries used +in the compilation and packaging process. The content of these +libraries is of interest primarily to the packaging engineers, *Note +The Package Release Engineer View::. + + Finally, the `packages', `packages/xemacs-packages', and +`packages/mule-packages' directories contain `Makefile's and include +files to control the package creation process. The `Makefile's in +`packages/xemacs-packages' and `packages/mule-packages' simply define +the default sets of known packages and include `../iterate.rules', +which implements recursive building of all target packages. + + The `make' infrastructure in `packages' includes + +`Makefile' + controls building of individual packages, local installation, and + bundling of "sumo" tarballs + +`iterate.rules' + controls recursive builds of multiple packages + +`meta-iterate.rules' + This is used by higher-level subdirectories that do not directly + contain packages. Subdirectories directly containing packages + should use iterate.rules instead. + +`XEmacs.rules' + provides the rules for building and packaging. Included by all + package `Makefile's. + +`Local.rules' + provides local configuration, such as installation targets and + staging directories, as well as a number of kludges (many now + obsolete) required for building packages on the Windows platform. + +`Local.rules.template' + a template for Local.rules, liberally commented + +`Local.rules.mk' + consistency checking for `Local.rules', included by both the + top-level `Makefile' and by `XEmacs.rules'. + +`Local.rules.inc' + a file to `include' in package `Makefile's to be able to get at + variables in `Local.rules' _before_ including `XEmacs.rules'. + +`package-compile.el' + compile environment (_e.g._, load-path) setup. + + Of these, only `Local.rules' and `package-compile.el' need to be +modified by the library maintainer. The changes to Local.rules affect +only your environment. This should need to be done only once when +first preparing the source environment. The necessary modifications to +`package-compile.el' need to be done for each package and are discussed +in the next section, *Note Control Files::. + + +File: lispref.info, Node: Control Files, Next: Obtaining, Prev: Infrastructure, Up: The Library Maintainer View + +3.2.2 Control Files +------------------- + +Each package source must contain a number of control files in the +top-level directory. These files in general can be created and then +ignored, except for a few variables that need to be updated when new +versions are released. In most cases even adding, renaming, and +removing library source files can be handled by generic rules. + + The package control files include + +`Makefile' + Must set a few `make' variables used by the administrative + utilities, and defines a couple of package-building targets to + depend on appropriate targets defined generically in + `XEmacs.rules'. It may also provide various variables and rules + to transform the source tree structure into that expected by the + run-time system. + +`package-info.in' + Provides a template for package information to be provided to the + administrative utilities. Static variables that are rarely changed + (such as the package's name) are entered as literals. Some + variables are generated by the build process (build dates and MD5 + checksums) and are automatically filled in. Finally, some + variables that change irregularly (dependences and even version + numbers) are set as `make' variables in the `Makefile'. + +`ChangeLog' + Not strictly required, but normally a ChangeLog will be added by + the XEmacs package maintainer if different from the upstream + maintainer. + +`_pkg.el' + Generated. Simply does a `package-provide' for the package. + +`auto-autoloads.el' + Generated. Read when XEmacs is initialized, and provides + autoloads for defuns and other forms in the sources that are + marked with an "autoload cookie" (`;;;###autoload'. + +`custom-loads.el' + Generated. Read when XEmacs is initialized, and informs the + Customize subsystem how to find the defcustom forms needed to + create Customization forms for the usre configuration variables of + the package. + + +File: lispref.info, Node: Obtaining, Prev: Control Files, Up: The Library Maintainer View + +3.2.3 Obtaining the XEmacs Packaging System and Required Utilities +------------------------------------------------------------------ + +Currently both the infrastructure for creating XEmacs packages and the +package sources themselves are available only by CVS. See +`http://www.xemacs.org/Develop/cvsaccess.html' for more intformation. + + The XEmacs Packaging System currently requires GNU `make', and +XEmacs, to build packages. + + +File: lispref.info, Node: The Package Release Engineer View, Prev: The Library Maintainer View, Up: Package Overview + +3.2.4 The Package Release Engineer View +--------------------------------------- + +The XEmacs Package Release Engineer is responsible for keeping the +system coherent. The changes to `packages/package-compile.el' and +`packages/xemacs-packages/Makefile' required to make the package +available to others, and for building SUMO tarballs, _etc_, are done by +the Package Release Engineer, not individual library maintainers. + + The Package Release Engineer also maintains assorted infrastructure +for actually making releases. These are generally available for +inspection in the `xemacs-builds' module in the CVS repository. + + +File: lispref.info, Node: Package Terminology, Next: Building Packages, Prev: Package Overview, Up: Packaging + +Package Terminology: +==================== + +3.2.5 Libraries and Packages +---------------------------- + +A Lisp "library" is a single loadable file containing Lisp code. It +may be in source or byte-compiled form. A Lisp "package" is a set of +one or more libraries, usually related to each other in some way, +bundled with administrative information for convenient distribution. + +3.2.6 Package Flavors +--------------------- + +There are two main flavors of packages. + +*Regular Packages* + A regular package is a set of Lisp libraries design to cooperate + with one another. A very complex example is Gnus. One may not in + general safely remove any of the component libraries. + +*Single-File Packages* + A single-file package is a collection of thematically related but + otherwise independent Lisp libraries. These libraries are bundled + together for convenience of the maintainers. Usually individual + libraries may be deleted at will without any loss of functionality + of other libraries in the package. However, we would recommend + that you follow this rule of thumb: "When in doubt, don't delete". + If it's really that big a deal, request that the maintainers + split the package into smaller aggregations. + +3.2.7 Package Distributions +--------------------------- + +XEmacs Lisp packages are distributed in two ways. "Binary packages" +are used by system administrators and end users. They are packaged in a +form convenient for direct installation into an XEmacs package +hierarchy. "Source packages" are for developers and include all files +necessary for rebuilding byte-compiled lisp and creating tarballs for +distribution or installation. This is all of the package author's +source code plus all of the files necessary to build distribution +tarballs (Unix Tar format files, gzipped for space savings). +(Occasionally sources that are not relevant to XEmacs are usually +renamed to `file.upstream'.) + + Currently, source packages are only available via CVS. See +`http://www.xemacs.org/Develop/cvsaccess.html' for details. + + The package distributions are also split according to major features +required in XEmacs to support them. At present there are "generic" +packages, which can be loaded by _any_ XEmacs, and "Mule" packages, +which _require_ Mule support or they will cause errors when loaded. +Note that there is no guarantee that a generic package will have any +useful functionality in a minimally configured XEmacs. As long as any +XEmacs can successfully load the package's libraries (perhaps given +other required Lisp libraries), it will be classified as generic. At +the present time only Mule packages need be treated specially, and even +those only if they contain multibyte characters. + + +File: lispref.info, Node: Building Packages, Next: Makefile Targets, Prev: Package Terminology, Up: Packaging + +Building Packages: +================== + +Currently, source packages are only available via anonymous CVS. See +`http://www.xemacs.org/Develop/cvsaccess.html' for details of checking +out the `packages' module. + +3.2.8 Prerequisites for Building Source Packages +------------------------------------------------ + +`GNU cp' + +`GNU install' + (or a BSD compatible install program). + +`GNU make' + (3.79 or later preferred). + +`makeinfo' + (4.2 from texinfo-4.2) + +`GNU tar' + (or equivalent). + +`GNU gzip' + (or equivalent). + +`A properly configured `Local.rules' file.' + *Note Local.rules File::. + + And of course, XEmacs, 21.0 or higher. + +3.3 What You Can Do With Source Packages +======================================== + +The packages CVS sources are most useful for creating XEmacs package +tarballs for installation into your own XEmacs installations or for +distributing to others. + + It should be noted that most of the package `Makefile's do _not_ +need to contain _any_ target rules. Everything is handled from the +`XEmacs.rules' file, located in the toplevel directory of the packages +source tree. + + +File: lispref.info, Node: Makefile Targets, Next: Local.rules File, Prev: Building Packages, Up: Packaging + +4 `Makefile' targets +******************** + +The following targets can be used when running `make' to build the +packages: + +`mostlyclean' + Removes any documentation files that have been processed by TeX. + +`clean' + Does a `mostlyclean', plus removes generated postscript and dvi + files. Also removes any generated .elc files, along with the + normal .elc files in the package and HTML and .info files. + +`distclean' + Use this when preparing a distribution. It kills anything that + can be rebuilt. + +`extraclean' + Does a `distclean' and also removes any backup files (`*~') and + `core' files. + +`package-info' + Creates the `package-info' file from the `package-info.in' and + writes an entry in the `package-index' file. + +`bindist' + Builds the package, including any Texinfo documentation (info + format), writes an entry into the `package-index' file and builds + a tarball of the package. Also writes an entry into + `setup-packages.ini' which is later used in the creation of + netinstaller's `setup.ini'. + +`install' + Builds and installs a package + +`install-only' + Doesn't build anything, just installs it. + +`autoloads' + Generate the package's `auto-autoloads.el' file. + +`binkit' + Creates the directories needed for installation and copies the + files there. Basically this is an alias for `install-only'. + +`html' + Builds the HTML versions of the documentation. + +`compile' + Does most of the work. Builds the elcs, infos at a minimum. + +4.0.1 The targets that most people would be interested in would be: +------------------------------------------------------------------- + + * `all' + + * `bindist' + + * `html' + + * `install' + + * `install-only' + + * `clean' + + * `distclean' + + +File: lispref.info, Node: Local.rules File, Next: Creating Packages, Prev: Makefile Targets, Up: Packaging + +The Local.rules File: +===================== + +This file in `packages' provides the XEmacs Packaging System with +information about the local configuration and environment. To create +`Local.rules', simply copy `Local.rules.template' from that directory to +`Local.rules' and edit it to suit your needs. + + These are the variables in `Local.rules' that you may need to +provide values for: + +`XEMACS' + The name (and path if needed) of the XEmacs binary to use for + building the packages. The default is `xemacs'. + +`XEMACS_21_5' + This will enable some, as yet, unimplemented features in XEmacs + 21.5 and above. For now leave this blank (the default) regardless + of the XEmacs version you are using. + +`BUILD_WITHOUT_MULE' + Set this to `t' if you are using a non-Mule XEmacs. The default is + that this variable is not set (blank) which means to build _with_ + Mule. + +`XEMACS_NATIVE_NT' + Set this to `t' if you are using a native Microsoft Windows build + of XEmacs (not a Cygwin build) to build the packages. *N.B.* To + Windows users, you still need the Cygwin environment to actually + build the packages. + +`XEMACS_INSTALLED_PACKAGES_ROOT' + Set this to the root of where you want the packages to be + installed. Under this directory will hang `xemacs-packages' and + `mule-packages'. See NONMULE_INSTALLED_PACKAGES_ROOT and + MULE_INSTALLED_PACKAGES_ROOT. The default for this is + `/usr/local/lib/xemacs'. Which may not be what you want if you are + developing XEmacs. To quote the comments in + `Local.rules.template': + + If you are developing XEmacs, you probably don't want to + install the packages under /usr/local, which is where the + stable, released version of XEmacs goes. Instead, we suggest + a layout as described in the base README file of recent + versions of XEmacs. In a nutshell, we suggest you put your + source under /src/xemacs, and under this put the package + sources in package-src/, and the installed packages in + xemacs-packages/ and mule-packages/. If you do everything + this way, you might want to set things as follows: + + XEMACS_INSTALLED_PACKAGES_ROOT = ${XEMACS_PACKAGES_BASE}/.. + + which puts the xemacs-packages/ and mule-packages/ + directories as sisters of the package-src/ directory, and you + have to tell configure the location of the installed packages + using `-package-path', something like + + configure + -package-path=/src/xemacs/xemacs-packages;/src/xemacs/mule-packages + +`symlink' + The default is unset (blank). If you set this to `t' then `make + install' will create a "symlink farm" of the installed packages + under XEMACS_INSTALLED_PACKAGES_ROOT. Obviously, for this to + work, your system has to support symbolic links. This is as close + as you can get to "running in place" for the packages. + +`NONMULE_INSTALLED_PACKAGES_ROOT' + This is where the non-Mule packages get installed to. The default + is `${XEMACS_INSTALLED_PACKAGES_ROOT}/xemacs-packages'. + +`MULE_INSTALLED_PACKAGES_ROOT' + This is where the Mule packages get installed to. The default is + `${XEMACS_INSTALLED_PACKAGES_ROOT}/mule-packages'. + +`NONMULE_PACKAGES' + A whitespace separated list of non-Mule packages to build/install. + + NONMULE_PACKAGES = bbdb gnus xemacs-base prog-modes + + The value for this variable can also be the symbol + `xemacs-packages', which means to build/install _all_ of the + non-Mule packages. The default is `xemacs-packages'. + +`MULE_PACKAGES' + A whitespace separated list of Mule packages to build/install. + + MULE_PACKAGES = mule-base leim locale + + The value for this variable can also be the symbol + `mule-packages', which means to build/install _all_ of the Mule + packages. The default is `mule-packages'. + +`PACKAGE_INDEX' + The name of the package-index file. The default is `package-index' + and you probably don't need to worry about changing it. + +`INSTALL' + The path to a BSD compatible install program. The default is + `install -c'. + +`TAR' + The path to GNU/tar. The default is `tar'. + +`BZIP2' + The path to the bzip2 compression program. The default is unset + (blank). If this is set `.tar.bz2' archives will be built _in + addition to_ the `.tar.gz' archives. + +`EXCLUDES' + For things that you _don't_ want to go into the package tarballs. + It takes the same format as GNU/tar's `--exclude' option. The + default is: + + EXCLUDES = \ + --exclude 'CVS' \ + --exclude 'RCS' \ + --exclude 'SCCS' \ + --exclude '*~' \ + --exclude '*.orig' \ + --exclude '*.rej' \ + --exclude '.\#*' + +`VANILLA' + Set to the XEmacs command line option that forces running in + "vanilla" mode. The default is `-vanilla'. You wouldn't ever + need to alter this. + +`BATCH' + How to put XEmacs into "batch" mode. It also sets a couple of + other things and in the normal course of events you wouldn't need + to alter this from the default which is: + + BATCH = $(VANILLA) -batch -eval \ + '(setq stack-trace-on-error t \ + load-always-display-messages t \ + load-ignore-out-of-date-elc-files t \ + load-show-full-path-in-messages t)' + +`MAKEINFO' + The path to `makeinfo'. The default is `makeinfo' + +`INSTALL_HTML' + Set this to `t' if you want to install HTML versions of the Texinfo + documentation. The default is unset (blank). + +`TEXI2HTML' + The path to the program that can convert Texinfo source to HTML. + The default is `texi2html'. + +`TEXI2DVI' + The path to the program that can convert Texinfo source to DVI. + The default is `texi2dvi' + +`DVIPS' + The path to the program that can convert DVI to Postscript. The + default is `dvips' + +`TEXI2PDF' + The path to the program that can convert Texinfo source to PDF + format. The default is `texi2pdf'. + +`TEX' + The path to TeX. The default is `tex' + +`MSGFMT' + The path to msgfmt. The default is `msgfmt' + +`RCOPY' + The path to your copy command (GNU cp). The default is dependent + on whether or not SYMLINK is set (`t'). + + If SYMLINK is unset (blank), RCOPY's default is `cp -af'. If + SYMLINK is set (`t'), RCOPY's default is `cp --force --recursive + --symbolic-link'. + + It should be noted that in most cases the defaults should be fine. +Most people will probably only need to alter: + + * XEMACS_INSTALLED_PACKAGES_ROOT + + * NONMULE_INSTALLED_PACKAGES_ROOT + + * MULE_INSTALLED_PACKAGES_ROOT + + * NONMULE_PACKAGES + + * MULE_PACKAGES + + +File: lispref.info, Node: Creating Packages, Next: Documenting Packages, Prev: Local.rules File, Up: Packaging + +5 Creating Packages: +******************** + +Creating a package from an existing Lisp library is not very difficult. + + In addition to the Lisp libraries themselves, you need a *Note +package-info.in:: file and a simple *Note Makefile::. The rest is done +by `XEmacs.rules', part of the packaging system infrastructure. + +* Menu: + +* package-info.in:: package-info.in +* Makefile:: `Makefile' + + +File: lispref.info, Node: package-info.in, Next: Makefile, Up: Creating Packages + +6 package-info.in +***************** + +`package-info.in' contains information that gets injected into the +`package-index' file when `make bindist' is run. Here is a real world +example from the xemacs-base package (a description of each field +follows the example): + + (xemacs-base + (standards-version 1.1 + version VERSION + author-version AUTHOR_VERSION + date DATE + build-date BUILD_DATE + maintainer MAINTAINER + distribution xemacs + priority high + category CATEGORY + dump nil + description "Fundamental XEmacs support, you almost certainly need this." + filename FILENAME + md5sum MD5SUM + size SIZE + provides (add-log advice-preload advice annotations assoc case-table chistory comint-xemacs comint compile debug ebuff-menu echistory edmacro ehelp electric enriched env facemenu ffap helper imenu iso-syntax macros novice outline passwd pp regexp-opt regi ring shell skeleton sort thing time-stamp timezone tq xbm-button xpm-button) + requires (REQUIRES) + type regular + )) + +Description of the Fields in `package-info.in': +----------------------------------------------- + +`NAME' + The name of the package. In the case of the example it is + `xemacs-base'. + +`standards-version' + Part of the internal package infrastructure, its value should + always be `1.1'. Do not change this. + +`version' + This is the XEmacs package version number of the package. It is + set from the `Makefile' variable VERSION. This is something that + the XEmacs Package Release Engineer deals with so there is no need + for a package maintainer to touch it. In `package-info.in' just + put the place-marker, `VERSION' here. + +`author-version' + This is the package's internal, or `upstream' version number if it + has one. It is set from the `Makefile' variable AUTHOR_VERSION. + +`date' + This is the date of the last change made to the package. It is + auto-generated at build time, taken from the package's toplevel + `ChangeLog'. + +`build-date' + The date the package was built. It is auto-generated. + +`maintainer' + This is the name and email address of the package's maintainer. + It is taken from the `Makefile' variable MAINTAINER. + +`distribution' + An unused field, leave as `xemacs' + +`priority' + An unused field, can be any of `high', `medium', or `low'. + +`category' + The `category' of the package. It is taken from the `Makefile' + variable CATEGORY and can be either `standard' for non-Mule + packages, or `mule' for Mule packages. The is also provision for + `unsupported' in this field which would be for packages that + XEmacs.org do not distribute. + + *N.B.* As yet, the XEmacs Packaging System does _not_ support this + type of package. It will in the future. + +`dump' + Unused. Always `nil' + +`description' + A free form short description of the package. + +`filename' + The file name of the package's binary tarball. It is generated at + build time by `make bindist'. + +`md5sum' + The MD5 message digest of the package's binary tarball. Generated + at build time by `make bindist'. + +`size' + The size in bytes of the package's binary tarball. Generated at + build time. + +`provides' + A whitespace separated list of _all_ the features the package + provides. Surround the list with parens. + +`requires' + Taken from the `Makefile' variable REQUIRES. It is a list of all + the package's dependencies, including any macros and defstructs + that need to be inlined. + + `REQUIRES' cannot be correctly computed from the calls to + `require' in the package's library sources. `REQUIRES' is used to + ensure that all macro and defstruct definitions used by the + package are available at build time. This is not merely a matter + of efficiency, to get the expansions inlined. In fact, it is + _impossible_ to call a macro by name in byte-compiled Emacs Lisp + code. Thus, if the macro expansion is not inlined, the call will + result in an error at run-time! Thus, packages providing + libraries that would be loaded because of autoload definitions + must also be included. + +`type' + Can either be `regular' for a regular package, or `single-file' + for a single file package. + + *N.B.* This doesn't refer to the number of lisp files in a + package. A single-file package can have multiple lisp files in it. + *Note Package Terminology::. + + The fields in `package-info.in' that need to be changed directly are: + + * NAME + + * description + + * provides + + * type + + Everything else is either set from the appropriate `Makefile' +variable, is auto-generated at build time, or is static. + + +File: lispref.info, Node: Makefile, Prev: package-info.in, Up: Creating Packages + +7 `Makefile' +************ + +The `Makefile' is quite stylized. The idea is similar to an +`Imakefile' or an `automake' file: the complexity is hidden in generic +rules files, in this case the `XEmacs.rules' include file in the top +directory of the packages hierarchy. + + It is important to note that the XEmacs used to compile packages is +the bare minimum: it is called with the `-no-autoloads'. This means +that anything not dumped into XEmacs by default needs to be specified +in the `REQUIRES' variable (for packaged Lisp) or in some cases the +`PRELOADS' (autoloads used in libraries mentioned in `PRELOADS'). + + There isn't much to an XEmacs Packaging System `Makefile', basically +it just contains a few `Makefile' variables and that's it. See the +example. + + Here is a real world example, from the `build' package: + + # Makefile for build lisp code + + # This file is part of XEmacs. + + # XEmacs 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 2, or (at your option) any + # later version. + + # XEmacs 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 XEmacs; see the file COPYING. If not, write to + # the Free Software Foundation, Inc., 59 Temple Place - Suite 330, + # Boston, MA 02111-1307, USA. + + # For the time being, remove MULE_ELCS from the all dependencies if + # building without Mule. + + VERSION = 1.10 + AUTHOR_VERSION = 2.02 + MAINTAINER = Adrian Aichner + PACKAGE = build + PKG_TYPE = regular + REQUIRES = xemacs-base pcl-cvs dired w3 prog-modes + CATEGORY = standard + + ELCS = build.elc build-report.elc + + STANDARD_DOCS = t + + include ../../XEmacs.rules + + Most packages don't need any more than what you see above. It is +usually _not_ necessary to specify any special `Makefile' rules. +Everything is handled from the `*.rules' files in the toplevel of the +package source hierarchy. + + Of course, with that said, there are always exceptions to the rule. +If you think that your package will need some special `Makefile' +hackery contact the XEmacs developers . We +distribute over 100 packages so the chances are good that you won't be +the first to need such hackery and it is probably already catered for. + +`Makefile' Variables Explained: +------------------------------- + +A number of `make' variables are defined by the XEmacs Packaging +System. Some are required, others are optional. Of course your +`Makefile' may define other variables for private use, but you should +be careful not to choose names that conflict with variables defined and +used by the XEmacs Packaging System. + + The required variables are described in the table below. The +corresponding field names for `package-info.in', where relevant, are +given in parentheses. + +`VERSION' + (version) The version of the XEmacs package, a numeric literal (a + decimal fixed-point number with two-places of precision). The + only person who ever needs to touch this is the XEmacs Packages + Release Engineer. + +`AUTHOR_VERSION' + (author-version) The upstream author's version, an uninterpreted + literal. + +`MAINTAINER' + (maintainer) A literal containing the XEmacs package's maintainer + and his/her email address. + +`PACKAGE' + The name of the package, a literal + +`PKG_TYPE' + The type of package, a literal containing either `regular' for + regular packages, or `single-file' for single-file packages. This + should feed the `type' field in `package-info.in', but currently + it doesn't. + + *N.B.* `single-file' here does _not_ refer to the number of lisp + files in a package. *Note Package Terminology::. + +`CATEGORY' + (category) A literal, either `standard' or `mule'. The non-Mule + packages are `standard' and the Mule packages are, you guessed it, + `mule'. This field is used at package installation time as part of + the process of determining where a package should be installed to. + +`REQUIRES' + (requires) A list of packages required to correctly build this + package. + + Note that the usual form in `package-info.in' already has the + parentheses, so the `make' variable should be set to a + space-separated list of package names _not_ enclosed in + parentheses. + + The list is of _packages_, not _libraries_, as would ordinarily be + provided to the Lisp `require' function. + + `REQUIRES' cannot be correctly computed from the calls to + `require' in the package's library sources. `REQUIRES' is used to + ensure that all macro and defstruct definitions used by the + package are available at build time. This is not merely a matter + of efficiency, to get the expansions inlined. In fact, it is + _impossible_ to call a macro by name in byte-compiled Emacs Lisp + code. Thus, if the macro expansion is not inlined, the call will + result in an error at run-time! Thus, packages providing + libraries that would be loaded because of autoload definitions + must also be included. + +`ELCS' + The list of the byte-compiled Lisp files used by the package. + These files and their `.el' versions will be included in the binary + package. This variable determines which libraries will be + byte-compiled. These libraries are also deleted by `make clean'. + + Note there is no sanity-checking done on this variable. If you put + `.el' files in here, they will not be compiled and they _will_ be + deleted by `make clean'. You would surely be very distressed if + that happened, so be very careful. If this variable is left + empty, none of your Lisp code will be compiled or packaged. This + would be a less than amusing surprise, too. + + We don't consider this a feature, of course. Please do submit + code to do sanity checking to . + + Optional, but commonly used variables are explained below. + +`ELCS_1' + A list of extra byte-compiled Lisp files used by the package to be + installed in a subdirectory of the package's lisp directory. The + same care should be taken with this as with ELCS in regard to + `make clean'. + +`ELCS_1_DEST' + The name of the subdirectory for the ELCS_1 files to be installed + to. Be sure to include `$(PACKAGE)/' as part of the name. + + ELCS_1_DEST = $(PACKAGE)/extra + + Would put the ELCS_1 files for the package, `foo' into + `xemacs-packages/lisp/foo/extra/'. + +`EARLY_GENERATED_LISP' + For additional `.el' files that will be generated before any + byte-compiling happens. Use this for `autoload-type' files. You + must write `Makefile' rules to build these files. + +`GENERATED_LISP' + For additional `.el' files that will be generated at + byte-compilation time. You must write `Makefile' rules to build + these files. + +`PRELOADS' + This is used if you need to pass extra command line arguments to + XEmacs to build the package. For instance, a specification for + loading libraries containing macros before compiling the Lisp in + the package. This is spliced directly into the invocation of + XEmacs for byte-compilation, so it must contain the `-l' flag for + XEmacs: + + PRELOADS=-l ./apackage-macros.el -l ../bpackage/lisp/bpackage-macros.el + + Preloads are loaded before `package-compile.el', so the LOAD-PATH + is minimal. Therefore `PRELOADS' must specify a full path to + packaged Lisp. The base LOAD-PATH does include the core Lisp + directory, so core libraries are found. + +`AUTOLOAD_PATH' + The subdirectory in the package's source tree where the `.el' files + reside. This is where the `auto-autoloads.el' file will be placed. + + *N.B.* There is no need to use this variable if the `.el' files + are in the package's toplevel directory. AUTOLOAD_PATH defaults + to `.'. + +`PACKAGE_SUPPRESS' + Place calls to `package-suppress' here to indicate Lisp libraries + that should only be available to particular versions of XEmacs. + For example: + + PACKAGE_SUPPRESS = \ + (package-suppress 'xemacs-base \"regexp-opt\" '(emacs-version>= 21 5 11)) \ + (package-suppress 'xemacs-base \"easy-mmode\" '(emacs-version>= 21 5 11)) + + *N.B.* This feature has not yet been implemented in XEmacs yet. + It will appear in an upcoming version of XEmacs 21.5. + +`STANDARD_DOCS' + Set this to `t' if your package's Texinfo source file is located in + the package's toplevel directory _and_ is named `$(PACKAGE).texi'. + +`EXPLICIT_DOCS' + Use this to explicitly list Texinfo sources that _aren't_ in the + package's toplevel directory. For example: + + EXPLICIT_DOCS = texi/$(PACKAGE).texi + + See DOCS_TXI_EXTENSION and DOCS_TEXINFO_EXTENSION if you don't use + the `.texi' file extension on your Texinfo sources. + +`EXTRA_TEXI_FILES' + List here extra Texinfo source files needed to build your + documentation. Whatever is listed here is passed on to `makeinfo' + as a dependency. + +`EXTRA_HTML_FILES' + Use this to specify extra `.html' files to output. + +`DOCS_TEXINFO_EXTENSION' + Set this to `t' if your Texinfo source files have a `.texinfo' + extension. + +`DOCS_TXI_EXTENSION' + Set this to `t' if your Texinfo source files have a `.txi' + extension. + +`EXTRA_DOC_FILES' + Files listed here will be installed to `.../man/$(PACKAGE)/'. For + example, you might want to list TeX files or `.eps' files here. + +`EXTRA_SOURCES' + Other files (such as extra Lisp sources or an upstream `Makefile') + that are normally placed in the installed Lisp directory, but not + byte-compiled. These files are _preserved_ by the `clean' targets. + +`LIBSRC_FILES' + For files that need to be installed to `lib-src/$(PACKAGE)/'. If + the files listed here need to be built you will have to write + `Makefile' rules to do so. + +`DATA_FILES' + Any data files, such as pixmaps, READMEs, and ChangeLogs. These + must be paths relative to the root of the package's source tree. + These files will be copied to `$(DATA_DEST)' for installation. + Any directory component of the path for a file will be stripped, + so that the file ends up in `$(DATA_DEST)', not in a subdiredtory. + +`DATA_DEST' + The directory where the files in DATA_FILES are installed to. It + is a subdirectory of the installed `etc/' directory. Be sure to + prefix this value with `$(PACKAGE)', for example: + + DATA_DEST = $(PACKAGE)/foo + + Would put files into `.../etc/$(PACKAGE)/foo/'. + +`DATA_1_FILES ... DATA_35_FILES' + For data files that need to go into a different directory from + DATA_DEST. + +`DATA_1_DEST ... DATA_35_DEST' + The name of the subdirectory for files specified in DATA_N_FILES. + And like DATA_DEST, be sure to prefix `$(PACKAGE)' to the value of + these variables. + +`EXTRA_DEPENDENCIES' + For additional files to build that aren't appropriate to place in + any other `Makefile' variable. You will need to write `Makefile' + rules to build these files. + +7.1 `package-compile.el' +======================== + +The XEmacs Packaging System does not automatically become aware of your +package simply because there is a new subtree. If any package, +including your own, requires any of your files, it must be explicitly +added to the compile environment or loads/requires that search +load-path will fail. The changes that need to be made are + +*an entry in `package-directory-map'* + This tells the XEmacs Packaging System which distribution + (currently `xemacs-packages' or `mule-packages') your package is + found in. It then looks in the distribution subdirectory whose + name is the same as the package's. + +*an entry in the `cond' in `package-name-to-directory'* + This is optional; it is necessary only if you keep your Lisp code + somewhere other than the top-level directory of the package's + source tree, eg, in `packages/xemacs-packages/PACKAGE/lisp'. + + This only needs to be done once, when the package is first added to +the XEmacs Packaging System. (Well, when you randomly change the +subdirectory layout, too.) Your changes to `package-compile.el' must +be cleared and checked in by the XEmacs Package Release Engineer before +your package will build correctly from a fresh checkout. + + This is unfortunate; it works pretty well once set up, but can cause +confusion when first building a package in the XEmacs Packaging System +context. In particular, if the `package-directory-map' entry for a +required package, including the package itself, is not found, the +necessary requires will not be executed by `package-compile.el'. If +required functions are executed (under `eval-when-compile'), they won't +be found and the compile will fail. If required function is actually a +macro, the byte compiler will not recognize that, compile a function +call to the macro. This will cause a run-time error because the +byte-code interpreter does not know how to execute macros. (Macros can +always be expanded at compile-time, and this is more efficient.) + + If your package keeps some or all Lisp code somewhere other than the +top directory, then an entry in `package-name-to-directory' is also +necessary, or requires will fail, leading to the problems just +described. + + +File: lispref.info, Node: Documenting Packages, Next: Issues, Prev: Creating Packages, Up: Packaging + +Documenting Packages: +===================== + +Some random notes on documenting your package. + + Do write a Texinfo file. It's not that hard to do basically, and +even using the more advanced features of Texinfo soon become natural. +For a start, just grab the template `Samples/package.texi' from the +XEmacs Packaging System source tree, and drop your current README into +the Top node. At least this way your documentation will be accessible +from the standard Info readers. Next, try to add lots of +cross-referencing and logical markup, and then node structure. + + Address both end users and developer issues. You may not be the +maintainer forever. + + If you are maintaining a package that is part of the GNU Emacs +distribution, you'll likely find that you occasionally synchronize your +package with the GNU Emacs sources. When you synch a file, +conventionally you should place a comment just above the standard `;;; +Code' comment that looks like this: + + ;; Synched with: + ;; GNU Emacs 21.1, 2002-02-08, Stephen Turnbull + + This comment is a status flag; the ChangeLog doesn't really give the +same information. + + Do maintain a detailed ChangeLog. + + +File: lispref.info, Node: Issues, Prev: Documenting Packages, Up: Packaging + +7.2 Issues +========== + +To be completed. + + +File: lispref.info, Node: Lisp Data Types, Next: Numbers, Prev: Packaging, Up: Top + +8 Lisp Data Types +***************** + +A Lisp "object" is a piece of data used and manipulated by Lisp +programs. For our purposes, a "type" or "data type" is a set of +possible objects. + + Every object belongs to at least one type. Objects of the same type +have similar structures and may usually be used in the same contexts. +Types can overlap, and objects can belong to two or more types. +Consequently, we can ask whether an object belongs to a particular type, +but not for "the" type of an object. + + A few fundamental object types are built into XEmacs. These, from +which all other types are constructed, are called "primitive types". +Each object belongs to one and only one primitive type. These types +include "integer", "character" (starting with XEmacs 20.0), "float", +"cons", "symbol", "string", "vector", "bit-vector", "subr", +"compiled-function", "hash-table", "range-table", "char-table", +"weak-list", and several special types, such as "buffer", that are +related to editing. (*Note Editing Types::.) + + Each primitive type has a corresponding Lisp function that checks +whether an object is a member of that type. + + Note that Lisp is unlike many other languages in that Lisp objects +are "self-typing": the primitive type of the object is implicit in the +object itself. For example, if an object is a vector, nothing can treat +it as a number; Lisp knows it is a vector, not a number. + + In most languages, the programmer must declare the data type of each +variable, and the type is known by the compiler but not represented in +the data. Such type declarations do not exist in XEmacs Lisp. A Lisp +variable can have any type of value, and it remembers whatever value +you store in it, type and all. + + This chapter describes the purpose, printed representation, and read +syntax of each of the standard types in Emacs Lisp. Details on how to +use these types can be found in later chapters. + +* Menu: + +* Printed Representation:: How Lisp objects are represented as text. +* Comments:: Comments and their formatting conventions. +* Primitive Types:: List of all primitive types in XEmacs. +* Programming Types:: Types found in all Lisp systems. +* Editing Types:: Types specific to XEmacs. +* Window-System Types:: Types specific to windowing systems. +* Type Predicates:: Tests related to types. +* Equality Predicates:: Tests of equality between any two objects. + + +File: lispref.info, Node: Printed Representation, Next: Comments, Up: Lisp Data Types + +8.1 Printed Representation and Read Syntax +========================================== + +The "printed representation" of an object is the format of the output +generated by the Lisp printer (the function `prin1') for that object. +The "read syntax" of an object is the format of the input accepted by +the Lisp reader (the function `read') for that object. Most objects +have more than one possible read syntax. Some types of object have no +read syntax; except for these cases, the printed representation of an +object is also a read syntax for it. + + In other languages, an expression is text; it has no other form. In +Lisp, an expression is primarily a Lisp object and only secondarily the +text that is the object's read syntax. Often there is no need to +emphasize this distinction, but you must keep it in the back of your +mind, or you will occasionally be very confused. + + Every type has a printed representation. Some types have no read +syntax, since it may not make sense to enter objects of these types +directly in a Lisp program. For example, the buffer type does not have +a read syntax. Objects of these types are printed in "hash notation": +the characters `#<' followed by a descriptive string (typically the +type name followed by the name of the object), and closed with a +matching `>'. Hash notation cannot be read at all, so the Lisp reader +signals the error `invalid-read-syntax' whenever it encounters `#<'. + + (current-buffer) + => # + + When you evaluate an expression interactively, the Lisp interpreter +first reads the textual representation of it, producing a Lisp object, +and then evaluates that object (*note Evaluation::). However, +evaluation and reading are separate activities. Reading returns the +Lisp object represented by the text that is read; the object may or may +not be evaluated later. *Note Input Functions::, for a description of +`read', the basic function for reading objects. + + +File: lispref.info, Node: Comments, Next: Primitive Types, Prev: Printed Representation, Up: Lisp Data Types + +8.2 Comments +============ + +A "comment" is text that is written in a program only for the sake of +humans that read the program, and that has no effect on the meaning of +the program. In Lisp, a semicolon (`;') starts a comment if it is not +within a string or character constant. The comment continues to the +end of line. The Lisp reader discards comments; they do not become +part of the Lisp objects which represent the program within the Lisp +system. + + The `#@COUNT' construct, which skips the next COUNT characters, is +useful for program-generated comments containing binary data. The +XEmacs Lisp byte compiler uses this in its output files (*note Byte +Compilation::). It isn't meant for source files, however. + + *Note Comment Tips::, for conventions for formatting comments. + + +File: lispref.info, Node: Primitive Types, Next: Programming Types, Prev: Comments, Up: Lisp Data Types + +8.3 Primitive Types +=================== + +For reference, here is a list of all the primitive types that may exist +in XEmacs. Note that some of these types may not exist in some XEmacs +executables; that depends on the options that XEmacs was configured +with. + + * bit-vector + + * buffer + + * char-table + + * character + + * charset + + * coding-system + + * cons + + * color-instance + + * compiled-function + + * console + + * database + + * device + + * event + + * extent + + * face + + * float + + * font-instance + + * frame + + * glyph + + * hash-table + + * image-instance + + * integer + + * keymap + + * marker + + * process + + * range-table + + * specifier + + * string + + * subr + + * subwindow + + * symbol + + * toolbar-button + + * tooltalk-message + + * tooltalk-pattern + + * vector + + * weak-list + + * window + + * window-configuration + + * x-resource + + In addition, the following special types are created internally but +will never be seen by Lisp code. You may encounter them, however, if +you are debugging XEmacs. The printed representation of these objects +begins `# ?Q ?q => ?q + (char-int ?Q) => 81 + ;; Under XEmacs 19: + ?Q => 81 ?q => 113 + + You can use the same syntax for punctuation characters, but it is +often a good idea to add a `\' so that the Emacs commands for editing +Lisp code don't get confused. For example, `?\ ' is the way to write +the space character. If the character is `\', you _must_ use a second +`\' to quote it: `?\\'. XEmacs 20 always prints punctuation characters +with a `\' in front of them, to avoid confusion. + + You can express the characters Control-g, backspace, tab, newline, +vertical tab, formfeed, return, and escape as `?\a', `?\b', `?\t', +`?\n', `?\v', `?\f', `?\r', `?\e', respectively. Their character codes +are 7, 8, 9, 10, 11, 12, 13, and 27 in decimal. Thus, + + ;; Under XEmacs 20: + ?\a => ?\^G ; `C-g' + (char-int ?\a) => 7 + ?\b => ?\^H ; backspace, , `C-h' + (char-int ?\b) => 8 + ?\t => ?\t ; tab, , `C-i' + (char-int ?\t) => 9 + ?\n => ?\n ; newline, , `C-j' + ?\v => ?\^K ; vertical tab, `C-k' + ?\f => ?\^L ; formfeed character, `C-l' + ?\r => ?\r ; carriage return, , `C-m' + ?\e => ?\^[ ; escape character, , `C-[' + ?\\ => ?\\ ; backslash character, `\' + ;; Under XEmacs 19: + ?\a => 7 ; `C-g' + ?\b => 8 ; backspace, , `C-h' + ?\t => 9 ; tab, , `C-i' + ?\n => 10 ; newline, , `C-j' + ?\v => 11 ; vertical tab, `C-k' + ?\f => 12 ; formfeed character, `C-l' + ?\r => 13 ; carriage return, , `C-m' + ?\e => 27 ; escape character, , `C-[' + ?\\ => 92 ; backslash character, `\' + + These sequences which start with backslash are also known as "escape +sequences", because backslash plays the role of an escape character; +this usage has nothing to do with the character . + + Control characters may be represented using yet another read syntax. +This consists of a question mark followed by a backslash, caret, and the +corresponding non-control character, in either upper or lower case. For +example, both `?\^I' and `?\^i' are valid read syntax for the character +`C-i', the character whose value is 9. + + Instead of the `^', you can use `C-'; thus, `?\C-i' is equivalent to +`?\^I' and to `?\^i': + + ;; Under XEmacs 20: + ?\^I => ?\t ?\C-I => ?\t + (char-int ?\^I) => 9 + ;; Under XEmacs 19: + ?\^I => 9 ?\C-I => 9 + + There is also a character read syntax beginning with `\M-'. This +sets the high bit of the character code (same as adding 128 to the +character code). For example, `?\M-A' stands for the character with +character code 193, or 128 plus 65. You should _not_ use this syntax +in your programs. It is a holdover of yet another confoundance disease +from earlier Emacsen. (This was used to represent keyboard input with +the key set, thus the `M'; however, it conflicts with the +legitimate ISO-8859-1 interpretation of the character code. For +example, character code 193 is a lowercase `a' with an acute accent, in +ISO-8859-1.) + + Finally, the most general read syntax consists of a question mark +followed by a backslash and the character code in octal (up to three +octal digits); thus, `?\101' for the character `A', `?\001' for the +character `C-a', and `?\002' for the character `C-b'. Although this +syntax can represent any ASCII character, it is preferred only when the +precise octal value is more important than the ASCII representation. + + ;; Under XEmacs 20: + ?\012 => ?\n ?\n => ?\n ?\C-j => ?\n + ?\101 => ?A ?A => ?A + ;; Under XEmacs 19: + ?\012 => 10 ?\n => 10 ?\C-j => 10 + ?\101 => 65 ?A => 65 + + A backslash is allowed, and harmless, preceding any character without +a special escape meaning; thus, `?\+' is equivalent to `?+'. There is +no reason to add a backslash before most characters. However, you +should add a backslash before any of the characters `()\|;'`"#.,' to +avoid confusing the Emacs commands for editing Lisp code. Also add a +backslash before whitespace characters such as space, tab, newline and +formfeed. However, it is cleaner to use one of the easily readable +escape sequences, such as `\t', instead of an actual whitespace +character such as a tab. + + +File: lispref.info, Node: Symbol Type, Next: Sequence Type, Prev: Character Type, Up: Programming Types + +8.4.4 Symbol Type +----------------- + +A "symbol" in XEmacs Lisp is an object with a name. The symbol name +serves as the printed representation of the symbol. In ordinary use, +the name is unique--no two symbols have the same name. + + A symbol can serve as a variable, as a function name, or to hold a +property list. Or it may serve only to be distinct from all other Lisp +objects, so that its presence in a data structure may be recognized +reliably. In a given context, usually only one of these uses is +intended. But you can use one symbol in all of these ways, +independently. + + A symbol name can contain any characters whatever. Most symbol names +are written with letters, digits, and the punctuation characters +`-+=*/'. Such names require no special punctuation; the characters of +the name suffice as long as the name does not look like a number. (If +it does, write a `\' at the beginning of the name to force +interpretation as a symbol.) The characters `_~!@$%^&:<>{}' are less +often used but also require no special punctuation. Any other +characters may be included in a symbol's name by escaping them with a +backslash. In contrast to its use in strings, however, a backslash in +the name of a symbol simply quotes the single character that follows the +backslash. For example, in a string, `\t' represents a tab character; +in the name of a symbol, however, `\t' merely quotes the letter `t'. +To have a symbol with a tab character in its name, you must actually +use a tab (preceded with a backslash). But it's rare to do such a +thing. + + Common Lisp note: In Common Lisp, lower case letters are always + "folded" to upper case, unless they are explicitly escaped. In + Emacs Lisp, upper case and lower case letters are distinct. + + Here are several examples of symbol names. Note that the `+' in the +fifth example is escaped to prevent it from being read as a number. +This is not necessary in the sixth example because the rest of the name +makes it invalid as a number. + + foo ; A symbol named `foo'. + FOO ; A symbol named `FOO', different from `foo'. + char-to-string ; A symbol named `char-to-string'. + 1+ ; A symbol named `1+' + ; (not `+1', which is an integer). + \+1 ; A symbol named `+1' + ; (not a very readable name). + \(*\ 1\ 2\) ; A symbol named `(* 1 2)' (a worse name). + +-*/_~!@$%^&=:<>{} ; A symbol named `+-*/_~!@$%^&=:<>{}'. + ; These characters need not be escaped. + + +File: lispref.info, Node: Sequence Type, Next: Cons Cell Type, Prev: Symbol Type, Up: Programming Types + +8.4.5 Sequence Types +-------------------- + +A "sequence" is a Lisp object that represents an ordered set of +elements. There are two kinds of sequence in XEmacs Lisp, lists and +arrays. Thus, an object of type list or of type array is also +considered a sequence. + + Arrays are further subdivided into strings, vectors, and bit vectors. +Vectors can hold elements of any type, but string elements must be +characters, and bit vector elements must be either 0 or 1. However, the +characters in a string can have extents (*note Extents::) and text +properties (*note Text Properties::) like characters in a buffer; +vectors do not support extents or text properties even when their +elements happen to be characters. + + Lists, strings, vectors, and bit vectors are different, but they have +important similarities. For example, all have a length L, and all have +elements which can be indexed from zero to L minus one. Also, several +functions, called sequence functions, accept any kind of sequence. For +example, the function `elt' can be used to extract an element of a +sequence, given its index. *Note Sequences Arrays Vectors::. + + It is impossible to read the same sequence twice, since sequences are +always created anew upon reading. If you read the read syntax for a +sequence twice, you get two sequences with equal contents. There is one +exception: the empty list `()' always stands for the same object, `nil'. + + +File: lispref.info, Node: Cons Cell Type, Next: Array Type, Prev: Sequence Type, Up: Programming Types + +8.4.6 Cons Cell and List Types +------------------------------ + +A "cons cell" is an object comprising two pointers named the CAR and +the CDR. Each of them can point to any Lisp object. + + A "list" is a series of cons cells, linked together so that the CDR +of each cons cell points either to another cons cell or to the empty +list. *Note Lists::, for functions that work on lists. Because most +cons cells are used as part of lists, the phrase "list structure" has +come to refer to any structure made out of cons cells. + + The names CAR and CDR have only historical meaning now. The +original Lisp implementation ran on an IBM 704 computer which divided +words into two parts, called the "address" part and the "decrement"; +CAR was an instruction to extract the contents of the address part of a +register, and CDR an instruction to extract the contents of the +decrement. By contrast, "cons cells" are named for the function `cons' +that creates them, which in turn is named for its purpose, the +construction of cells. + + Because cons cells are so central to Lisp, we also have a word for +"an object which is not a cons cell". These objects are called "atoms". + + The read syntax and printed representation for lists are identical, +and consist of a left parenthesis, an arbitrary number of elements, and +a right parenthesis. + + Upon reading, each object inside the parentheses becomes an element +of the list. That is, a cons cell is made for each element. The CAR +of the cons cell points to the element, and its CDR points to the next +cons cell of the list, which holds the next element in the list. The +CDR of the last cons cell is set to point to `nil'. + + A list can be illustrated by a diagram in which the cons cells are +shown as pairs of boxes. (The Lisp reader cannot read such an +illustration; unlike the textual notation, which can be understood by +both humans and computers, the box illustrations can be understood only +by humans.) The following represents the three-element list `(rose +violet buttercup)': + + ___ ___ ___ ___ ___ ___ + |___|___|--> |___|___|--> |___|___|--> nil + | | | + | | | + --> rose --> violet --> buttercup + + In this diagram, each box represents a slot that can refer to any +Lisp object. Each pair of boxes represents a cons cell. Each arrow is +a reference to a Lisp object, either an atom or another cons cell. + + In this example, the first box, the CAR of the first cons cell, +refers to or "contains" `rose' (a symbol). The second box, the CDR of +the first cons cell, refers to the next pair of boxes, the second cons +cell. The CAR of the second cons cell refers to `violet' and the CDR +refers to the third cons cell. The CDR of the third (and last) cons +cell refers to `nil'. + + Here is another diagram of the same list, `(rose violet buttercup)', +sketched in a different manner: + + --------------- ---------------- ------------------- + | car | cdr | | car | cdr | | car | cdr | + | rose | o-------->| violet | o-------->| buttercup | nil | + | | | | | | | | | + --------------- ---------------- ------------------- + + A list with no elements in it is the "empty list"; it is identical +to the symbol `nil'. In other words, `nil' is both a symbol and a list. + + Here are examples of lists written in Lisp syntax: + + (A 2 "A") ; A list of three elements. + () ; A list of no elements (the empty list). + nil ; A list of no elements (the empty list). + ("A ()") ; A list of one element: the string `"A ()"'. + (A ()) ; A list of two elements: `A' and the empty list. + (A nil) ; Equivalent to the previous. + ((A B C)) ; A list of one element + ; (which is a list of three elements). + + Here is the list `(A ())', or equivalently `(A nil)', depicted with +boxes and arrows: + + ___ ___ ___ ___ + |___|___|--> |___|___|--> nil + | | + | | + --> A --> nil + +* Menu: + +* Dotted Pair Notation:: An alternative syntax for lists. +* Association List Type:: A specially constructed list. + + +File: lispref.info, Node: Dotted Pair Notation, Next: Association List Type, Up: Cons Cell Type + +8.4.6.1 Dotted Pair Notation +............................ + +"Dotted pair notation" is an alternative syntax for cons cells that +represents the CAR and CDR explicitly. In this syntax, `(A . B)' +stands for a cons cell whose CAR is the object A, and whose CDR is the +object B. Dotted pair notation is therefore more general than list +syntax. In the dotted pair notation, the list `(1 2 3)' is written as +`(1 . (2 . (3 . nil)))'. For `nil'-terminated lists, the two +notations produce the same result, but list notation is usually clearer +and more convenient when it is applicable. When printing a list, the +dotted pair notation is only used if the CDR of a cell is not a list. + + Here's how box notation can illustrate dotted pairs. This example +shows the pair `(rose . violet)': + + ___ ___ + |___|___|--> violet + | + | + --> rose + + Dotted pair notation can be combined with list notation to represent +a chain of cons cells with a non-`nil' final CDR. For example, `(rose +violet . buttercup)' is equivalent to `(rose . (violet . buttercup))'. +The object looks like this: + + ___ ___ ___ ___ + |___|___|--> |___|___|--> buttercup + | | + | | + --> rose --> violet + + These diagrams make it evident why `(rose . violet . buttercup)' is +invalid syntax; it would require a cons cell that has three parts +rather than two. + + The list `(rose violet)' is equivalent to `(rose . (violet))' and +looks like this: + + ___ ___ ___ ___ + |___|___|--> |___|___|--> nil + | | + | | + --> rose --> violet + + Similarly, the three-element list `(rose violet buttercup)' is +equivalent to `(rose . (violet . (buttercup)))'. It looks like this: + + ___ ___ ___ ___ ___ ___ + |___|___|--> |___|___|--> |___|___|--> nil + | | | + | | | + --> rose --> violet --> buttercup + + +File: lispref.info, Node: Association List Type, Prev: Dotted Pair Notation, Up: Cons Cell Type + +8.4.6.2 Association List Type +............................. + +An "association list" or "alist" is a specially-constructed list whose +elements are cons cells. In each element, the CAR is considered a +"key", and the CDR is considered an "associated value". (In some +cases, the associated value is stored in the CAR of the CDR.) +Association lists are often used as stacks, since it is easy to add or +remove associations at the front of the list. + + For example, + + (setq alist-of-colors + '((rose . red) (lily . white) (buttercup . yellow))) + +sets the variable `alist-of-colors' to an alist of three elements. In +the first element, `rose' is the key and `red' is the value. + + *Note Association Lists::, for a further explanation of alists and +for functions that work on alists. + + +File: lispref.info, Node: Array Type, Next: String Type, Prev: Cons Cell Type, Up: Programming Types + +8.4.7 Array Type +---------------- + +An "array" is composed of an arbitrary number of slots for referring to +other Lisp objects, arranged in a contiguous block of memory. +Accessing any element of an array takes the same amount of time. In +contrast, accessing an element of a list requires time proportional to +the position of the element in the list. (Elements at the end of a +list take longer to access than elements at the beginning of a list.) + + XEmacs defines three types of array, strings, vectors, and bit +vectors. A string is an array of characters, a vector is an array of +arbitrary objects, and a bit vector is an array of 1's and 0's. All are +one-dimensional. (Most other programming languages support +multidimensional arrays, but they are not essential; you can get the +same effect with an array of arrays.) Each type of array has its own +read syntax; see *Note String Type::, *Note Vector Type::, and *Note +Bit Vector Type::. + + An array may have any length up to the largest integer; but once +created, it has a fixed size. The first element of an array has index +zero, the second element has index 1, and so on. This is called +"zero-origin" indexing. For example, an array of four elements has +indices 0, 1, 2, and 3. + + The array type is contained in the sequence type and contains the +string type, the vector type, and the bit vector type. + + +File: lispref.info, Node: String Type, Next: Vector Type, Prev: Array Type, Up: Programming Types + +8.4.8 String Type +----------------- + +A "string" is an array of characters. Strings are used for many +purposes in XEmacs, as can be expected in a text editor; for example, as +the names of Lisp symbols, as messages for the user, and to represent +text extracted from buffers. Strings in Lisp are constants: evaluation +of a string returns the same string. + + The read syntax for strings is a double-quote, an arbitrary number of +characters, and another double-quote, `"like this"'. The Lisp reader +accepts the same formats for reading the characters of a string as it +does for reading single characters (without the question mark that +begins a character literal). You can enter a nonprinting character such +as tab or `C-a' using the convenient escape sequences, like this: `"\t, +\C-a"'. You can include a double-quote in a string by preceding it +with a backslash; thus, `"\""' is a string containing just a single +double-quote character. (*Note Character Type::, for a description of +the read syntax for characters.) + + The printed representation of a string consists of a double-quote, +the characters it contains, and another double-quote. However, you must +escape any backslash or double-quote characters in the string with a +backslash, like this: `"this \" is an embedded quote"'. + + The newline character is not special in the read syntax for strings; +if you write a new line between the double-quotes, it becomes a +character in the string. But an escaped newline--one that is preceded +by `\'--does not become part of the string; i.e., the Lisp reader +ignores an escaped newline while reading a string. + + "It is useful to include newlines + in documentation strings, + but the newline is \ + ignored if escaped." + => "It is useful to include newlines + in documentation strings, + but the newline is ignored if escaped." + + A string can hold extents and properties of the text it contains, in +addition to the characters themselves. This enables programs that copy +text between strings and buffers to preserve the extents and properties +with no special effort. *Note Extents::, *Note Text Properties::. + + Note that FSF GNU Emacs has a special read and print syntax for +strings with text properties, but XEmacs does not currently implement +this. It was judged better not to include this in XEmacs because it +entails that `equal' return `nil' when passed a string with text +properties and the equivalent string without text properties, which is +often counter-intuitive. + + *Note Strings and Characters::, for functions that work on strings. + + +File: lispref.info, Node: Vector Type, Next: Bit Vector Type, Prev: String Type, Up: Programming Types + +8.4.9 Vector Type +----------------- + +A "vector" is a one-dimensional array of elements of any type. It +takes a constant amount of time to access any element of a vector. (In +a list, the access time of an element is proportional to the distance of +the element from the beginning of the list.) + + The printed representation of a vector consists of a left square +bracket, the elements, and a right square bracket. This is also the +read syntax. Like numbers and strings, vectors are considered constants +for evaluation. + + [1 "two" (three)] ; A vector of three elements. + => [1 "two" (three)] + + *Note Vectors::, for functions that work with vectors. + + +File: lispref.info, Node: Bit Vector Type, Next: Function Type, Prev: Vector Type, Up: Programming Types + +8.4.10 Bit Vector Type +---------------------- + +A "bit vector" is a one-dimensional array of 1's and 0's. It takes a +constant amount of time to access any element of a bit vector, as for +vectors. Bit vectors have an extremely compact internal representation +(one machine bit per element), which makes them ideal for keeping track +of unordered sets, large collections of boolean values, etc. + + The printed representation of a bit vector consists of `#*' followed +by the bits in the vector. This is also the read syntax. Like +numbers, strings, and vectors, bit vectors are considered constants for +evaluation. + + #*00101000 ; A bit vector of eight elements. + => #*00101000 + + *Note Bit Vectors::, for functions that work with bit vectors. + + +File: lispref.info, Node: Function Type, Next: Macro Type, Prev: Bit Vector Type, Up: Programming Types + +8.4.11 Function Type +-------------------- + +Just as functions in other programming languages are executable, "Lisp +function" objects are pieces of executable code. However, functions in +Lisp are primarily Lisp objects, and only secondarily the text which +represents them. These Lisp objects are lambda expressions: lists +whose first element is the symbol `lambda' (*note Lambda Expressions::). + + In most programming languages, it is impossible to have a function +without a name. In Lisp, a function has no intrinsic name. A lambda +expression is also called an "anonymous function" (*note Anonymous +Functions::). A named function in Lisp is actually a symbol with a +valid function in its function cell (*note Defining Functions::). + + Most of the time, functions are called when their names are written +in Lisp expressions in Lisp programs. However, you can construct or +obtain a function object at run time and then call it with the primitive +functions `funcall' and `apply'. *Note Calling Functions::. + + +File: lispref.info, Node: Macro Type, Next: Primitive Function Type, Prev: Function Type, Up: Programming Types + +8.4.12 Macro Type +----------------- + +A "Lisp macro" is a user-defined construct that extends the Lisp +language. It is represented as an object much like a function, but with +different parameter-passing semantics. A Lisp macro has the form of a +list whose first element is the symbol `macro' and whose CDR is a Lisp +function object, including the `lambda' symbol. + + Lisp macro objects are usually defined with the built-in `defmacro' +function, but any list that begins with `macro' is a macro as far as +XEmacs is concerned. *Note Macros::, for an explanation of how to +write a macro. + + +File: lispref.info, Node: Primitive Function Type, Next: Compiled-Function Type, Prev: Macro Type, Up: Programming Types + +8.4.13 Primitive Function Type +------------------------------ + +A "primitive function" is a function callable from Lisp but written in +the C programming language. Primitive functions are also called +"subrs" or "built-in functions". (The word "subr" is derived from +"subroutine".) Most primitive functions evaluate all their arguments +when they are called. A primitive function that does not evaluate all +its arguments is called a "special form" (*note Special Forms::). + + It does not matter to the caller of a function whether the function +is primitive. However, this does matter if you try to substitute a +function written in Lisp for a primitive of the same name. The reason +is that the primitive function may be called directly from C code. +Calls to the redefined function from Lisp will use the new definition, +but calls from C code may still use the built-in definition. + + The term "function" refers to all Emacs functions, whether written +in Lisp or C. *Note Function Type::, for information about the +functions written in Lisp. + + Primitive functions have no read syntax and print in hash notation +with the name of the subroutine. + + (symbol-function 'car) ; Access the function cell + ; of the symbol. + => # + (subrp (symbol-function 'car)) ; Is this a primitive function? + => t ; Yes. + + +File: lispref.info, Node: Compiled-Function Type, Next: Autoload Type, Prev: Primitive Function Type, Up: Programming Types + +8.4.14 Compiled-Function Type +----------------------------- + +The byte compiler produces "compiled-function objects". The evaluator +handles this data type specially when it appears as a function to be +called. *Note Byte Compilation::, for information about the byte +compiler. + + The printed representation for a compiled-function object is normally +`#'. If `print-readably' is true, however, it is +`#[...]'. + + +File: lispref.info, Node: Autoload Type, Next: Char Table Type, Prev: Compiled-Function Type, Up: Programming Types + +8.4.15 Autoload Type +-------------------- + +An "autoload object" is a list whose first element is the symbol +`autoload'. It is stored as the function definition of a symbol as a +placeholder for the real definition; it says that the real definition +is found in a file of Lisp code that should be loaded when necessary. +The autoload object contains the name of the file, plus some other +information about the real definition. + + After the file has been loaded, the symbol should have a new function +definition that is not an autoload object. The new definition is then +called as if it had been there to begin with. From the user's point of +view, the function call works as expected, using the function definition +in the loaded file. + + An autoload object is usually created with the function `autoload', +which stores the object in the function cell of a symbol. *Note +Autoload::, for more details. + + +File: lispref.info, Node: Char Table Type, Next: Hash Table Type, Prev: Autoload Type, Up: Programming Types + +8.4.16 Char Table Type +---------------------- + +(not yet documented) + + +File: lispref.info, Node: Hash Table Type, Next: Range Table Type, Prev: Char Table Type, Up: Programming Types + +8.4.17 Hash Table Type +---------------------- + +A "hash table" is a table providing an arbitrary mapping from one Lisp +object to another, using an internal indexing method called "hashing". +Hash tables are very fast (much more efficient that using an +association list, when there are a large number of elements in the +table). + + Hash tables have a special read syntax beginning with +`#s(hash-table' (this is an example of "structure" read syntax. This +notation is also used for printing when `print-readably' is `t'. + + Otherwise they print in hash notation (The "hash" in "hash notation" +has nothing to do with the "hash" in "hash table"), giving the number +of elements, total space allocated for elements, and a unique number +assigned at the time the hash table was created. (Hash tables +automatically resize as necessary so there is no danger of running out +of space for elements.) + + (make-hash-table :size 50) + => # + + *Note Hash Tables::, for information on how to create and work with +hash tables. + + +File: lispref.info, Node: Range Table Type, Next: Weak List Type, Prev: Hash Table Type, Up: Programming Types + +8.4.18 Range Table Type +----------------------- + +A "range table" is a table that maps from ranges of integers to +arbitrary Lisp objects. Range tables automatically combine overlapping +ranges that map to the same Lisp object, and operations are provided +for mapping over all of the ranges in a range table. + + Range tables have a special read syntax beginning with +`#s(range-table' (this is an example of "structure" read syntax, which +is also used for char tables and faces). + + (setq x (make-range-table)) + (put-range-table 20 50 'foo x) + (put-range-table 100 200 "bar" x) + x + => #s(range-table data ((20 50) foo (100 200) "bar")) + + *Note Range Tables::, for information on how to create and work with +range tables. + + +File: lispref.info, Node: Weak List Type, Prev: Range Table Type, Up: Programming Types + +8.4.19 Weak List Type +--------------------- + +(not yet documented) + + +File: lispref.info, Node: Editing Types, Next: Window-System Types, Prev: Programming Types, Up: Lisp Data Types + +8.5 Editing Types +================= + +The types in the previous section are common to many Lisp dialects. +XEmacs Lisp provides several additional data types for purposes +connected with editing. + +* Menu: + +* Buffer Type:: The basic object of editing. +* Marker Type:: A position in a buffer. +* Extent Type:: A range in a buffer or string, maybe with properties. +* Window Type:: Buffers are displayed in windows. +* Frame Type:: Windows subdivide frames. +* Device Type:: Devices group all frames on a display. +* Console Type:: Consoles group all devices with the same keyboard. +* Window Configuration Type:: Recording the way a frame is subdivided. +* Event Type:: An interesting occurrence in the system. +* Process Type:: A process running on the underlying OS. +* Stream Type:: Receive or send characters. +* Keymap Type:: What function a keystroke invokes. +* Syntax Table Type:: What a character means. +* Display Table Type:: How display tables are represented. +* Database Type:: A connection to an external DBM or DB database. +* Charset Type:: A character set (e.g. all Kanji characters), + under XEmacs/MULE. +* Coding System Type:: An object encapsulating a way of converting between + different textual encodings, under XEmacs/MULE. +* ToolTalk Message Type:: A message, in the ToolTalk IPC protocol. +* ToolTalk Pattern Type:: A pattern, in the ToolTalk IPC protocol. + + +File: lispref.info, Node: Buffer Type, Next: Marker Type, Up: Editing Types + +8.5.1 Buffer Type +----------------- + +A "buffer" is an object that holds text that can be edited (*note +Buffers::). Most buffers hold the contents of a disk file (*note +Files::) so they can be edited, but some are used for other purposes. +Most buffers are also meant to be seen by the user, and therefore +displayed, at some time, in a window (*note Windows::). But a buffer +need not be displayed in any window. + + The contents of a buffer are much like a string, but buffers are not +used like strings in XEmacs Lisp, and the available operations are +different. For example, insertion of text into a buffer is very +efficient, whereas "inserting" text into a string requires +concatenating substrings, and the result is an entirely new string +object. + + Each buffer has a designated position called "point" (*note +Positions::). At any time, one buffer is the "current buffer". Most +editing commands act on the contents of the current buffer in the +neighborhood of point. Many of the standard Emacs functions manipulate +or test the characters in the current buffer; a whole chapter in this +manual is devoted to describing these functions (*note Text::). + + Several other data structures are associated with each buffer: + + * a local syntax table (*note Syntax Tables::); + + * a local keymap (*note Keymaps::); + + * a local variable binding list (*note Buffer-Local Variables::); + + * a list of extents (*note Extents::); + + * and various other related properties. + +The local keymap and variable list contain entries that individually +override global bindings or values. These are used to customize the +behavior of programs in different buffers, without actually changing the +programs. + + A buffer may be "indirect", which means it shares the text of +another buffer. *Note Indirect Buffers::. + + Buffers have no read syntax. They print in hash notation, showing +the buffer name. + + (current-buffer) + => # + + +File: lispref.info, Node: Marker Type, Next: Extent Type, Prev: Buffer Type, Up: Editing Types + +8.5.2 Marker Type +----------------- + +A "marker" denotes a position in a specific buffer. Markers therefore +have two components: one for the buffer, and one for the position. +Changes in the buffer's text automatically relocate the position value +as necessary to ensure that the marker always points between the same +two characters in the buffer. + + Markers have no read syntax. They print in hash notation, giving the +current character position and the name of the buffer. + + (point-marker) + => # + + *Note Markers::, for information on how to test, create, copy, and +move markers. + + +File: lispref.info, Node: Extent Type, Next: Window Type, Prev: Marker Type, Up: Editing Types + +8.5.3 Extent Type +----------------- + +An "extent" specifies temporary alteration of the display appearance of +a part of a buffer (or string). It contains markers delimiting a range +of the buffer, plus a property list (a list whose elements are +alternating property names and values). Extents are used to present +parts of the buffer temporarily in a different display style. They +have no read syntax, and print in hash notation, giving the buffer name +and range of positions. + + Extents can exist over strings as well as buffers; the primary use +of this is to preserve extent and text property information as text is +copied from one buffer to another or between different parts of a +buffer. + + Extents have no read syntax. They print in hash notation, giving the +range of text they cover, the name of the buffer or string they are in, +the address in core, and a summary of some of the properties attached to +the extent. + + (extent-at (point)) + => # + + *Note Extents::, for how to create and use extents. + + Extents are used to implement text properties. *Note Text +Properties::. + + +File: lispref.info, Node: Window Type, Next: Frame Type, Prev: Extent Type, Up: Editing Types + +8.5.4 Window Type +----------------- + +A "window" describes the portion of the frame that XEmacs uses to +display a buffer. (In standard window-system usage, a "window" is what +XEmacs calls a "frame"; XEmacs confusingly uses the term "window" to +refer to what is called a "pane" in standard window-system usage.) +Every window has one associated buffer, whose contents appear in the +window. By contrast, a given buffer may appear in one window, no +window, or several windows. + + Though many windows may exist simultaneously, at any time one window +is designated the "selected window". This is the window where the +cursor is (usually) displayed when XEmacs is ready for a command. The +selected window usually displays the current buffer, but this is not +necessarily the case. + + Windows are grouped on the screen into frames; each window belongs to +one and only one frame. *Note Frame Type::. + + Windows have no read syntax. They print in hash notation, giving the +name of the buffer being displayed and a unique number assigned at the +time the window was created. (This number can be useful because the +buffer displayed in any given window can change frequently.) + + (selected-window) + => # + + *Note Windows::, for a description of the functions that work on +windows. + + +File: lispref.info, Node: Frame Type, Next: Device Type, Prev: Window Type, Up: Editing Types + +8.5.5 Frame Type +---------------- + +A FRAME is a rectangle on the screen (a "window" in standard +window-system terminology) that contains one or more non-overlapping +Emacs windows ("panes" in standard window-system terminology). A frame +initially contains a single main window (plus perhaps a minibuffer +window) which you can subdivide vertically or horizontally into smaller +windows. + + Frames have no read syntax. They print in hash notation, giving the +frame's type, name as used for resourcing, and a unique number assigned +at the time the frame was created. + + (selected-frame) + => # + + *Note Frames::, for a description of the functions that work on +frames. + + +File: lispref.info, Node: Device Type, Next: Console Type, Prev: Frame Type, Up: Editing Types + +8.5.6 Device Type +----------------- + +A "device" represents a single display on which frames exist. +Normally, there is only one device object, but there may be more than +one if XEmacs is being run on a multi-headed display (e.g. an X server +with attached color and mono screens) or if XEmacs is simultaneously +driving frames attached to different consoles, e.g. an X display and a +TTY connection. + + Devices do not have a read syntax. They print in hash notation, +giving the device's type, connection name, and a unique number assigned +at the time the device was created. + + (selected-device) + => # + + *Note Consoles and Devices::, for a description of several functions +related to devices. + + +File: lispref.info, Node: Console Type, Next: Window Configuration Type, Prev: Device Type, Up: Editing Types + +8.5.7 Console Type +------------------ + +A "console" represents a single keyboard to which devices (i.e. +displays on which frames exist) are connected. Normally, there is only +one console object, but there may be more than one if XEmacs is +simultaneously driving frames attached to different X servers and/or +TTY connections. (XEmacs is capable of driving multiple X and TTY +connections at the same time, and provides a robust mechanism for +handling the differing display capabilities of such heterogeneous +environments. A buffer with embedded glyphs and multiple fonts and +colors, for example, will display reasonably if it simultaneously +appears on a frame on a color X display, a frame on a mono X display, +and a frame on a TTY connection.) + + Consoles do not have a read syntax. They print in hash notation, +giving the console's type, connection name, and a unique number assigned +at the time the console was created. + + (selected-console) + => # + + *Note Consoles and Devices::, for a description of several functions +related to consoles. + + +File: lispref.info, Node: Window Configuration Type, Next: Event Type, Prev: Console Type, Up: Editing Types + +8.5.8 Window Configuration Type +------------------------------- + +A "window configuration" stores information about the positions, sizes, +and contents of the windows in a frame, so you can recreate the same +arrangement of windows later. + + Window configurations do not have a read syntax. They print in hash +notation, giving a unique number assigned at the time the window +configuration was created. + + (current-window-configuration) + => # + + *Note Window Configurations::, for a description of several functions +related to window configurations. + + +File: lispref.info, Node: Event Type, Next: Process Type, Prev: Window Configuration Type, Up: Editing Types + +8.5.9 Event Type +---------------- + +(not yet documented) + + +File: lispref.info, Node: Process Type, Next: Stream Type, Prev: Event Type, Up: Editing Types + +8.5.10 Process Type +------------------- + +The word "process" usually means a running program. XEmacs itself runs +in a process of this sort. However, in XEmacs Lisp, a process is a +Lisp object that designates a subprocess created by the XEmacs process. +Programs such as shells, GDB, ftp, and compilers, running in +subprocesses of XEmacs, extend the capabilities of XEmacs. + + An Emacs subprocess takes textual input from Emacs and returns +textual output to Emacs for further manipulation. Emacs can also send +signals to the subprocess. + + Process objects have no read syntax. They print in hash notation, +giving the name of the process, its associated process ID, and the +current state of the process: + + (process-list) + => (#) + + *Note Processes::, for information about functions that create, +delete, return information about, send input or signals to, and receive +output from processes. + + +File: lispref.info, Node: Stream Type, Next: Keymap Type, Prev: Process Type, Up: Editing Types + +8.5.11 Stream Type +------------------ + +A "stream" is an object that can be used as a source or sink for +characters--either to supply characters for input or to accept them as +output. Many different types can be used this way: markers, buffers, +strings, and functions. Most often, input streams (character sources) +obtain characters from the keyboard, a buffer, or a file, and output +streams (character sinks) send characters to a buffer, such as a +`*Help*' buffer, or to the echo area. + + The object `nil', in addition to its other meanings, may be used as +a stream. It stands for the value of the variable `standard-input' or +`standard-output'. Also, the object `t' as a stream specifies input +using the minibuffer (*note Minibuffers::) or output in the echo area +(*note The Echo Area::). + + Streams have no special printed representation or read syntax, and +print as whatever primitive type they are. + + *Note Read and Print::, for a description of functions related to +streams, including parsing and printing functions. + + +File: lispref.info, Node: Keymap Type, Next: Syntax Table Type, Prev: Stream Type, Up: Editing Types + +8.5.12 Keymap Type +------------------ + +A "keymap" maps keys typed by the user to commands. This mapping +controls how the user's command input is executed. + + NOTE: In XEmacs, a keymap is a separate primitive type. In FSF GNU +Emacs, a keymap is actually a list whose CAR is the symbol `keymap'. + + *Note Keymaps::, for information about creating keymaps, handling +prefix keys, local as well as global keymaps, and changing key bindings. + + +File: lispref.info, Node: Syntax Table Type, Next: Display Table Type, Prev: Keymap Type, Up: Editing Types + +8.5.13 Syntax Table Type +------------------------ + +Under XEmacs 20, a "syntax table" is a particular type of char table. +Under XEmacs 19, a syntax table a vector of 256 integers. In both +cases, each element defines how one character is interpreted when it +appears in a buffer. For example, in C mode (*note Major Modes::), the +`+' character is punctuation, but in Lisp mode it is a valid character +in a symbol. These modes specify different interpretations by changing +the syntax table entry for `+'. + + Syntax tables are used only for scanning text in buffers, not for +reading Lisp expressions. The table the Lisp interpreter uses to read +expressions is built into the XEmacs source code and cannot be changed; +thus, to change the list delimiters to be `{' and `}' instead of `(' +and `)' would be impossible. + + *Note Syntax Tables::, for details about syntax classes and how to +make and modify syntax tables. + + +File: lispref.info, Node: Display Table Type, Next: Database Type, Prev: Syntax Table Type, Up: Editing Types + +8.5.14 Display Table Type +------------------------- + +A "display table" specifies how to display each character code. Each +buffer and each window can have its own display table. A display table +is actually a vector of length 256, although in XEmacs 20 this may +change to be a particular type of char table. *Note Display Tables::. + + +File: lispref.info, Node: Database Type, Next: Charset Type, Prev: Display Table Type, Up: Editing Types + +8.5.15 Database Type +-------------------- + +(not yet documented) + + +File: lispref.info, Node: Charset Type, Next: Coding System Type, Prev: Database Type, Up: Editing Types + +8.5.16 Charset Type +------------------- + +(not yet documented) + + +File: lispref.info, Node: Coding System Type, Next: ToolTalk Message Type, Prev: Charset Type, Up: Editing Types + +8.5.17 Coding System Type +------------------------- + +(not yet documented) + + +File: lispref.info, Node: ToolTalk Message Type, Next: ToolTalk Pattern Type, Prev: Coding System Type, Up: Editing Types + +8.5.18 ToolTalk Message Type +---------------------------- + +(not yet documented) + + +File: lispref.info, Node: ToolTalk Pattern Type, Prev: ToolTalk Message Type, Up: Editing Types + +8.5.19 ToolTalk Pattern Type +---------------------------- + +(not yet documented) + + +File: lispref.info, Node: Window-System Types, Next: Type Predicates, Prev: Editing Types, Up: Lisp Data Types + +8.6 Window-System Types +======================= + +XEmacs also has some types that represent objects such as faces +(collections of display characters), fonts, and pixmaps that are +commonly found in windowing systems. + +* Menu: + +* Face Type:: A collection of display characteristics. +* Glyph Type:: An image appearing in a buffer or elsewhere. +* Specifier Type:: A way of controlling display characteristics on + a per-buffer, -frame, -window, or -device level. +* Font Instance Type:: The way a font appears on a particular device. +* Color Instance Type:: The way a color appears on a particular device. +* Image Instance Type:: The way an image appears on a particular device. +* Toolbar Button Type:: An object representing a button in a toolbar. +* Subwindow Type:: An externally-controlled window-system window + appearing in a buffer. +* X Resource Type:: A miscellaneous X resource, if Epoch support was + compiled into XEmacs. + + +File: lispref.info, Node: Face Type, Next: Glyph Type, Up: Window-System Types + +8.6.1 Face Type +--------------- + +(not yet documented) + + +File: lispref.info, Node: Glyph Type, Next: Specifier Type, Prev: Face Type, Up: Window-System Types + +8.6.2 Glyph Type +---------------- + +(not yet documented) + + +File: lispref.info, Node: Specifier Type, Next: Font Instance Type, Prev: Glyph Type, Up: Window-System Types + +8.6.3 Specifier Type +-------------------- + +(not yet documented) + + +File: lispref.info, Node: Font Instance Type, Next: Color Instance Type, Prev: Specifier Type, Up: Window-System Types + +8.6.4 Font Instance Type +------------------------ + +(not yet documented) + + +File: lispref.info, Node: Color Instance Type, Next: Image Instance Type, Prev: Font Instance Type, Up: Window-System Types + +8.6.5 Color Instance Type +------------------------- + +(not yet documented) + + +File: lispref.info, Node: Image Instance Type, Next: Toolbar Button Type, Prev: Color Instance Type, Up: Window-System Types + +8.6.6 Image Instance Type +------------------------- + +(not yet documented) + + +File: lispref.info, Node: Toolbar Button Type, Next: Subwindow Type, Prev: Image Instance Type, Up: Window-System Types + +8.6.7 Toolbar Button Type +------------------------- + +(not yet documented) + + +File: lispref.info, Node: Subwindow Type, Next: X Resource Type, Prev: Toolbar Button Type, Up: Window-System Types + +8.6.8 Subwindow Type +-------------------- + +(not yet documented) + + +File: lispref.info, Node: X Resource Type, Prev: Subwindow Type, Up: Window-System Types + +8.6.9 X Resource Type +--------------------- + +(not yet documented) + + +File: lispref.info, Node: Type Predicates, Next: Equality Predicates, Prev: Window-System Types, Up: Lisp Data Types + +8.7 Type Predicates +=================== + +The XEmacs Lisp interpreter itself does not perform type checking on +the actual arguments passed to functions when they are called. It could +not do so, since function arguments in Lisp do not have declared data +types, as they do in other programming languages. It is therefore up to +the individual function to test whether each actual argument belongs to +a type that the function can use. + + All built-in functions do check the types of their actual arguments +when appropriate, and signal a `wrong-type-argument' error if an +argument is of the wrong type. For example, here is what happens if you +pass an argument to `+' that it cannot handle: + + (+ 2 'a) + error--> Wrong type argument: integer-or-marker-p, a + + If you want your program to handle different types differently, you +must do explicit type checking. The most common way to check the type +of an object is to call a "type predicate" function. Emacs has a type +predicate for each type, as well as some predicates for combinations of +types. + + A type predicate function takes one argument; it returns `t' if the +argument belongs to the appropriate type, and `nil' otherwise. +Following a general Lisp convention for predicate functions, most type +predicates' names end with `p'. + + Here is an example which uses the predicates `listp' to check for a +list and `symbolp' to check for a symbol. + + (defun add-on (x) + (cond ((symbolp x) + ;; If X is a symbol, put it on LIST. + (setq list (cons x list))) + ((listp x) + ;; If X is a list, add its elements to LIST. + (setq list (append x list))) + (t + ;; We only handle symbols and lists. + (error "Invalid argument %s in add-on" x)))) + + Here is a table of predefined type predicates, in alphabetical order, +with references to further information. + +`annotationp' + *Note annotationp: Annotation Primitives. + +`arrayp' + *Note arrayp: Array Functions. + +`atom' + *Note atom: List-related Predicates. + +`bit-vector-p' + *Note bit-vector-p: Bit Vector Functions. + +`bitp' + *Note bitp: Bit Vector Functions. + +`boolean-specifier-p' + *Note boolean-specifier-p: Specifier Types. + +`buffer-glyph-p' + *Note buffer-glyph-p: Glyph Types. + +`buffer-live-p' + *Note buffer-live-p: Killing Buffers. + +`bufferp' + *Note bufferp: Buffer Basics. + +`button-event-p' + *Note button-event-p: Event Predicates. + +`button-press-event-p' + *Note button-press-event-p: Event Predicates. + +`button-release-event-p' + *Note button-release-event-p: Event Predicates. + +`case-table-p' + *Note case-table-p: Case Tables. + +`char-int-p' + *Note char-int-p: Character Codes. + +`char-or-char-int-p' + *Note char-or-char-int-p: Character Codes. + +`char-or-string-p' + *Note char-or-string-p: Predicates for Strings. + +`char-table-p' + *Note char-table-p: Char Tables. + +`characterp' + *Note characterp: Predicates for Characters. + +`color-instance-p' + *Note color-instance-p: Colors. + +`color-pixmap-image-instance-p' + *Note color-pixmap-image-instance-p: Image Instance Types. + +`color-specifier-p' + *Note color-specifier-p: Specifier Types. + +`commandp' + *Note commandp: Interactive Call. + +`compiled-function-p' + *Note compiled-function-p: Compiled-Function Type. + +`console-live-p' + *Note console-live-p: Connecting to a Console or Device. + +`consolep' + *Note consolep: Consoles and Devices. + +`consp' + *Note consp: List-related Predicates. + +`database-live-p' + *Note database-live-p: Connecting to a Database. + +`databasep' + *Note databasep: Databases. + +`device-live-p' + *Note device-live-p: Connecting to a Console or Device. + +`device-or-frame-p' + *Note device-or-frame-p: Basic Device Functions. + +`devicep' + *Note devicep: Consoles and Devices. + +`eval-event-p' + *Note eval-event-p: Event Predicates. + +`event-live-p' + *Note event-live-p: Event Predicates. + +`eventp' + *Note eventp: Events. + +`extent-live-p' + *Note extent-live-p: Creating and Modifying Extents. + +`extentp' + *Note extentp: Extents. + +`face-boolean-specifier-p' + *Note face-boolean-specifier-p: Specifier Types. + +`facep' + *Note facep: Basic Face Functions. + +`floatp' + *Note floatp: Predicates on Numbers. + +`font-instance-p' + *Note font-instance-p: Fonts. + +`font-specifier-p' + *Note font-specifier-p: Specifier Types. + +`frame-live-p' + *Note frame-live-p: Deleting Frames. + +`framep' + *Note framep: Frames. + +`functionp' + (not yet documented) + +`generic-specifier-p' + *Note generic-specifier-p: Specifier Types. + +`glyphp' + *Note glyphp: Glyphs. + +`hash-table-p' + *Note hash-table-p: Hash Tables. + +`icon-glyph-p' + *Note icon-glyph-p: Glyph Types. + +`image-instance-p' + *Note image-instance-p: Images. + +`image-specifier-p' + *Note image-specifier-p: Specifier Types. + +`integer-char-or-marker-p' + *Note integer-char-or-marker-p: Predicates on Markers. + +`integer-or-char-p' + *Note integer-or-char-p: Predicates for Characters. + +`integer-or-marker-p' + *Note integer-or-marker-p: Predicates on Markers. + +`integer-specifier-p' + *Note integer-specifier-p: Specifier Types. + +`integerp' + *Note integerp: Predicates on Numbers. + +`itimerp' + (not yet documented) + +`key-press-event-p' + *Note key-press-event-p: Event Predicates. + +`keymapp' + *Note keymapp: Creating Keymaps. + +`keywordp' + (not yet documented) + +`listp' + *Note listp: List-related Predicates. + +`markerp' + *Note markerp: Predicates on Markers. + +`misc-user-event-p' + *Note misc-user-event-p: Event Predicates. + +`mono-pixmap-image-instance-p' + *Note mono-pixmap-image-instance-p: Image Instance Types. + +`motion-event-p' + *Note motion-event-p: Event Predicates. + +`mouse-event-p' + *Note mouse-event-p: Event Predicates. + +`natnum-specifier-p' + *Note natnum-specifier-p: Specifier Types. + +`natnump' + *Note natnump: Predicates on Numbers. + +`nlistp' + *Note nlistp: List-related Predicates. + +`nothing-image-instance-p' + *Note nothing-image-instance-p: Image Instance Types. + +`number-char-or-marker-p' + *Note number-char-or-marker-p: Predicates on Markers. + +`number-or-marker-p' + *Note number-or-marker-p: Predicates on Markers. + +`numberp' + *Note numberp: Predicates on Numbers. + +`pointer-glyph-p' + *Note pointer-glyph-p: Glyph Types. + +`pointer-image-instance-p' + *Note pointer-image-instance-p: Image Instance Types. + +`process-event-p' + *Note process-event-p: Event Predicates. + +`processp' + *Note processp: Processes. + +`range-table-p' + *Note range-table-p: Range Tables. + +`ringp' + (not yet documented) + +`sequencep' + *Note sequencep: Sequence Functions. + +`specifierp' + *Note specifierp: Specifiers. + +`stringp' + *Note stringp: Predicates for Strings. + +`subrp' + *Note subrp: Function Cells. + +`subwindow-image-instance-p' + *Note subwindow-image-instance-p: Image Instance Types. + +`subwindowp' + *Note subwindowp: Subwindows. + +`symbolp' + *Note symbolp: Symbols. + +`syntax-table-p' + *Note syntax-table-p: Syntax Tables. + +`text-image-instance-p' + *Note text-image-instance-p: Image Instance Types. + +`timeout-event-p' + *Note timeout-event-p: Event Predicates. + +`toolbar-button-p' + *Note toolbar-button-p: Toolbar. + +`toolbar-specifier-p' + *Note toolbar-specifier-p: Toolbar. + +`user-variable-p' + *Note user-variable-p: Defining Variables. + +`vectorp' + *Note vectorp: Vectors. + +`weak-list-p' + *Note weak-list-p: Weak Lists. + +`window-configuration-p' + *Note window-configuration-p: Window Configurations. + +`window-live-p' + *Note window-live-p: Deleting Windows. + +`windowp' + *Note windowp: Basic Windows. + + The most general way to check the type of an object is to call the +function `type-of'. Recall that each object belongs to one and only +one primitive type; `type-of' tells you which one (*note Lisp Data +Types::). But `type-of' knows nothing about non-primitive types. In +most cases, it is more convenient to use type predicates than `type-of'. + + -- Function: type-of object + This function returns a symbol naming the primitive type of + OBJECT. The value is one of `bit-vector', `buffer', `char-table', + `character', `charset', `coding-system', `cons', `color-instance', + `compiled-function', `console', `database', `device', `event', + `extent', `face', `float', `font-instance', `frame', `glyph', + `hash-table', `image-instance', `integer', `keymap', `marker', + `process', `range-table', `specifier', `string', `subr', + `subwindow', `symbol', `toolbar-button', `tooltalk-message', + `tooltalk-pattern', `vector', `weak-list', `window', + `window-configuration', or `x-resource'. + + (type-of 1) + => integer + (type-of 'nil) + => symbol + (type-of '()) ; `()' is `nil'. + => symbol + (type-of '(x)) + => cons + + +File: lispref.info, Node: Equality Predicates, Prev: Type Predicates, Up: Lisp Data Types + +8.8 Equality Predicates +======================= + +Here we describe two functions that test for equality between any two +objects. Other functions test equality between objects of specific +types, e.g., strings. For these predicates, see the appropriate chapter +describing the data type. + + -- Function: eq object1 object2 + This function returns `t' if OBJECT1 and OBJECT2 are the same + object, `nil' otherwise. The "same object" means that a change in + one will be reflected by the same change in the other. + + `eq' returns `t' if OBJECT1 and OBJECT2 are integers with the same + value. Also, since symbol names are normally unique, if the + arguments are symbols with the same name, they are `eq'. For + other types (e.g., lists, vectors, strings), two arguments with + the same contents or elements are not necessarily `eq' to each + other: they are `eq' only if they are the same object. + + (The `make-symbol' function returns an uninterned symbol that is + not interned in the standard `obarray'. When uninterned symbols + are in use, symbol names are no longer unique. Distinct symbols + with the same name are not `eq'. *Note Creating Symbols::.) + + NOTE: Under XEmacs 19, characters are really just integers, and + thus characters and integers are `eq'. Under XEmacs 20, it was + necessary to preserve remnants of this in function such as `old-eq' + in order to maintain byte-code compatibility. Byte code compiled + under any Emacs 19 will automatically have calls to `eq' mapped to + `old-eq' when executed under XEmacs 20. + + (eq 'foo 'foo) + => t + + (eq 456 456) + => t + + (eq "asdf" "asdf") + => nil + + (eq '(1 (2 (3))) '(1 (2 (3)))) + => nil + + (setq foo '(1 (2 (3)))) + => (1 (2 (3))) + (eq foo foo) + => t + (eq foo '(1 (2 (3)))) + => nil + + (eq [(1 2) 3] [(1 2) 3]) + => nil + + (eq (point-marker) (point-marker)) + => nil + + + -- Function: old-eq object1 object2 + This function exists under XEmacs 20 and is exactly like `eq' + except that it suffers from the char-int confoundance disease. In + other words, it returns `t' if given a character and the + equivalent integer, even though the objects are of different types! + You should _not_ ever call this function explicitly in your code. + However, be aware that all calls to `eq' in byte code compiled + under version 19 map to `old-eq' in XEmacs 20. (Likewise for + `old-equal', `old-memq', `old-member', `old-assq' and + `old-assoc'.) + + ;; Remember, this does not apply under XEmacs 19. + ?A + => ?A + (char-int ?A) + => 65 + (old-eq ?A 65) + => t ; Eek, we've been infected. + (eq ?A 65) + => nil ; We are still healthy. + + -- Function: equal object1 object2 + This function returns `t' if OBJECT1 and OBJECT2 have equal + components, `nil' otherwise. Whereas `eq' tests if its arguments + are the same object, `equal' looks inside nonidentical arguments + to see if their elements are the same. So, if two objects are + `eq', they are `equal', but the converse is not always true. + + (equal 'foo 'foo) + => t + + (equal 456 456) + => t + + (equal "asdf" "asdf") + => t + (eq "asdf" "asdf") + => nil + + (equal '(1 (2 (3))) '(1 (2 (3)))) + => t + (eq '(1 (2 (3))) '(1 (2 (3)))) + => nil + + (equal [(1 2) 3] [(1 2) 3]) + => t + (eq [(1 2) 3] [(1 2) 3]) + => nil + + (equal (point-marker) (point-marker)) + => t + + (eq (point-marker) (point-marker)) + => nil + + Comparison of strings is case-sensitive. + + Note that in FSF GNU Emacs, comparison of strings takes into + account their text properties, and you have to use `string-equal' + if you want only the strings themselves compared. This difference + does not exist in XEmacs; `equal' and `string-equal' always return + the same value on the same strings. + + (equal "asdf" "ASDF") + => nil + + Two distinct buffers are never `equal', even if their contents are + the same. + + The test for equality is implemented recursively, and circular lists +may therefore cause infinite recursion (leading to an error). + + +File: lispref.info, Node: Numbers, Next: Strings and Characters, Prev: Lisp Data Types, Up: Top + +9 Numbers +********* + +XEmacs supports two numeric data types: "integers" and "floating point +numbers". Integers are whole numbers such as -3, 0, #b0111, #xFEED, +#o744. Their values are exact. The number prefixes `#b', `#o', and +`#x' are supported to represent numbers in binary, octal, and +hexadecimal notation (or radix). Floating point numbers are numbers +with fractional parts, such as -4.5, 0.0, or 2.71828. They can also be +expressed in exponential notation: 1.5e2 equals 150; in this example, +`e2' stands for ten to the second power, and is multiplied by 1.5. +Floating point values are not exact; they have a fixed, limited amount +of precision. + +* Menu: + +* Integer Basics:: Representation and range of integers. +* Float Basics:: Representation and range of floating point. +* Predicates on Numbers:: Testing for numbers. +* Comparison of Numbers:: Equality and inequality predicates. +* Numeric Conversions:: Converting float to integer and vice versa. +* Arithmetic Operations:: How to add, subtract, multiply and divide. +* Rounding Operations:: Explicitly rounding floating point numbers. +* Bitwise Operations:: Logical and, or, not, shifting. +* Math Functions:: Trig, exponential and logarithmic functions. +* Random Numbers:: Obtaining random integers, predictable or not. + + +File: lispref.info, Node: Integer Basics, Next: Float Basics, Up: Numbers + +9.1 Integer Basics +================== + +The range of values for an integer depends on the machine. The minimum +range is -134217728 to 134217727 (28 bits; i.e., -2**27 to 2**27 - 1), +but some machines may provide a wider range. Many examples in this +chapter assume an integer has 28 bits. + + The Lisp reader reads an integer as a sequence of digits with +optional initial sign and optional final period. + + 1 ; The integer 1. + 1. ; The integer 1. + +1 ; Also the integer 1. + -1 ; The integer -1. + 268435457 ; Also the integer 1, due to overflow. + 0 ; The integer 0. + -0 ; The integer 0. + + To understand how various functions work on integers, especially the +bitwise operators (*note Bitwise Operations::), it is often helpful to +view the numbers in their binary form. + + In 28-bit binary, the decimal integer 5 looks like this: + + 0000 0000 0000 0000 0000 0000 0101 + +(We have inserted spaces between groups of 4 bits, and two spaces +between groups of 8 bits, to make the binary integer easier to read.) + + The integer -1 looks like this: + + 1111 1111 1111 1111 1111 1111 1111 + +-1 is represented as 28 ones. (This is called "two's complement" +notation.) + + The negative integer, -5, is creating by subtracting 4 from -1. In +binary, the decimal integer 4 is 100. Consequently, -5 looks like this: + + 1111 1111 1111 1111 1111 1111 1011 + + In this implementation, the largest 28-bit binary integer is the +decimal integer 134,217,727. In binary, it looks like this: + + 0111 1111 1111 1111 1111 1111 1111 + + Since the arithmetic functions do not check whether integers go +outside their range, when you add 1 to 134,217,727, the value is the +negative integer -134,217,728: + + (+ 1 134217727) + => -134217728 + => 1000 0000 0000 0000 0000 0000 0000 + + Many of the following functions accept markers for arguments as well +as integers. (*Note Markers::.) More precisely, the actual arguments +to such functions may be either integers or markers, which is why we +often give these arguments the name INT-OR-MARKER. When the argument +value is a marker, its position value is used and its buffer is ignored. + + +File: lispref.info, Node: Float Basics, Next: Predicates on Numbers, Prev: Integer Basics, Up: Numbers + +9.2 Floating Point Basics +========================= + +XEmacs supports floating point numbers. The precise range of floating +point numbers is machine-specific; it is the same as the range of the C +data type `double' on the machine in question. + + The printed representation for floating point numbers requires either +a decimal point (with at least one digit following), an exponent, or +both. For example, `1500.0', `15e2', `15.0e2', `1.5e3', and `.15e4' +are five ways of writing a floating point number whose value is 1500. +They are all equivalent. You can also use a minus sign to write +negative floating point numbers, as in `-1.0'. + + Most modern computers support the IEEE floating point standard, which +provides for positive infinity and negative infinity as floating point +values. It also provides for a class of values called NaN or +"not-a-number"; numerical functions return such values in cases where +there is no correct answer. For example, `(sqrt -1.0)' returns a NaN. +For practical purposes, there's no significant difference between +different NaN values in XEmacs Lisp, and there's no rule for precisely +which NaN value should be used in a particular case, so this manual +doesn't try to distinguish them. XEmacs Lisp has no read syntax for +NaNs or infinities; perhaps we should create a syntax in the future. + + You can use `logb' to extract the binary exponent of a floating +point number (or estimate the logarithm of an integer): + + -- Function: logb number + This function returns the binary exponent of NUMBER. More + precisely, the value is the logarithm of NUMBER base 2, rounded + down to an integer. + + +File: lispref.info, Node: Predicates on Numbers, Next: Comparison of Numbers, Prev: Float Basics, Up: Numbers + +9.3 Type Predicates for Numbers +=============================== + +The functions in this section test whether the argument is a number or +whether it is a certain sort of number. The functions `integerp' and +`floatp' can take any type of Lisp object as argument (the predicates +would not be of much use otherwise); but the `zerop' predicate requires +a number as its argument. See also `integer-or-marker-p', +`integer-char-or-marker-p', `number-or-marker-p' and +`number-char-or-marker-p', in *Note Predicates on Markers::. + + -- Function: floatp object + This predicate tests whether its argument is a floating point + number and returns `t' if so, `nil' otherwise. + + `floatp' does not exist in Emacs versions 18 and earlier. + + -- Function: integerp object + This predicate tests whether its argument is an integer, and + returns `t' if so, `nil' otherwise. + + -- Function: numberp object + This predicate tests whether its argument is a number (either + integer or floating point), and returns `t' if so, `nil' otherwise. + + -- Function: natnump object + The `natnump' predicate (whose name comes from the phrase + "natural-number-p") tests to see whether its argument is a + nonnegative integer, and returns `t' if so, `nil' otherwise. 0 is + considered non-negative. + + -- Function: zerop number + This predicate tests whether its argument is zero, and returns `t' + if so, `nil' otherwise. The argument must be a number. + + These two forms are equivalent: `(zerop x)' == `(= x 0)'. + + +File: lispref.info, Node: Comparison of Numbers, Next: Numeric Conversions, Prev: Predicates on Numbers, Up: Numbers + +9.4 Comparison of Numbers +========================= + +To test numbers for numerical equality, you should normally use `=', +not `eq'. There can be many distinct floating point number objects +with the same numeric value. If you use `eq' to compare them, then you +test whether two values are the same _object_. By contrast, `=' +compares only the numeric values of the objects. + + At present, each integer value has a unique Lisp object in XEmacs +Lisp. Therefore, `eq' is equivalent to `=' where integers are +concerned. It is sometimes convenient to use `eq' for comparing an +unknown value with an integer, because `eq' does not report an error if +the unknown value is not a number--it accepts arguments of any type. +By contrast, `=' signals an error if the arguments are not numbers or +markers. However, it is a good idea to use `=' if you can, even for +comparing integers, just in case we change the representation of +integers in a future XEmacs version. + + There is another wrinkle: because floating point arithmetic is not +exact, it is often a bad idea to check for equality of two floating +point values. Usually it is better to test for approximate equality. +Here's a function to do this: + + (defconst fuzz-factor 1.0e-6) + (defun approx-equal (x y) + (or (and (= x 0) (= y 0)) + (< (/ (abs (- x y)) + (max (abs x) (abs y))) + fuzz-factor))) + + Common Lisp note: Comparing numbers in Common Lisp always requires + `=' because Common Lisp implements multi-word integers, and two + distinct integer objects can have the same numeric value. XEmacs + Lisp can have just one integer object for any given value because + it has a limited range of integer values. + + In addition to numbers, all of the following functions also accept +characters and markers as arguments, and treat them as their number +equivalents. + + -- Function: = number &rest more-numbers + This function returns `t' if all of its arguments are numerically + equal, `nil' otherwise. + + (= 5) + => t + (= 5 6) + => nil + (= 5 5.0) + => t + (= 5 5 6) + => nil + + -- Function: /= number &rest more-numbers + This function returns `t' if no two arguments are numerically + equal, `nil' otherwise. + + (/= 5 6) + => t + (/= 5 5 6) + => nil + (/= 5 6 1) + => t + + -- Function: < number &rest more-numbers + This function returns `t' if the sequence of its arguments is + monotonically increasing, `nil' otherwise. + + (< 5 6) + => t + (< 5 6 6) + => nil + (< 5 6 7) + => t + + -- Function: <= number &rest more-numbers + This function returns `t' if the sequence of its arguments is + monotonically nondecreasing, `nil' otherwise. + + (<= 5 6) + => t + (<= 5 6 6) + => t + (<= 5 6 5) + => nil + + -- Function: > number &rest more-numbers + This function returns `t' if the sequence of its arguments is + monotonically decreasing, `nil' otherwise. + + -- Function: >= number &rest more-numbers + This function returns `t' if the sequence of its arguments is + monotonically nonincreasing, `nil' otherwise. + + -- Function: max number &rest more-numbers + This function returns the largest of its arguments. + + (max 20) + => 20 + (max 1 2.5) + => 2.5 + (max 1 3 2.5) + => 3 + + -- Function: min number &rest more-numbers + This function returns the smallest of its arguments. + + (min -4 1) + => -4 + + +File: lispref.info, Node: Numeric Conversions, Next: Arithmetic Operations, Prev: Comparison of Numbers, Up: Numbers + +9.5 Numeric Conversions +======================= + +To convert an integer to floating point, use the function `float'. + + -- Function: float number + This returns NUMBER converted to floating point. If NUMBER is + already a floating point number, `float' returns it unchanged. + + There are four functions to convert floating point numbers to +integers; they differ in how they round. These functions accept +integer arguments also, and return such arguments unchanged. + + -- Function: truncate number + This returns NUMBER, converted to an integer by rounding towards + zero. + + -- Function: floor number &optional divisor + This returns NUMBER, converted to an integer by rounding downward + (towards negative infinity). + + If DIVISOR is specified, NUMBER is divided by DIVISOR before the + floor is taken; this is the division operation that corresponds to + `mod'. An `arith-error' results if DIVISOR is 0. + + -- Function: ceiling number + This returns NUMBER, converted to an integer by rounding upward + (towards positive infinity). + + -- Function: round number + This returns NUMBER, converted to an integer by rounding towards + the nearest integer. Rounding a value equidistant between two + integers may choose the integer closer to zero, or it may prefer + an even integer, depending on your machine. + + +File: lispref.info, Node: Arithmetic Operations, Next: Rounding Operations, Prev: Numeric Conversions, Up: Numbers + +9.6 Arithmetic Operations +========================= + +XEmacs Lisp provides the traditional four arithmetic operations: +addition, subtraction, multiplication, and division. Remainder and +modulus functions supplement the division functions. The functions to +add or subtract 1 are provided because they are traditional in Lisp and +commonly used. + + All of these functions except `%' return a floating point value if +any argument is floating. + + It is important to note that in XEmacs Lisp, arithmetic functions do +not check for overflow. Thus `(1+ 134217727)' may evaluate to +-134217728, depending on your hardware. + + -- Function: 1+ number + This function returns NUMBER plus one. NUMBER may be a number, + character or marker. Markers and characters are converted to + integers. + + For example, + + (setq foo 4) + => 4 + (1+ foo) + => 5 + + This function is not analogous to the C operator `++'--it does not + increment a variable. It just computes a sum. Thus, if we + continue, + + foo + => 4 + + If you want to increment the variable, you must use `setq', like + this: + + (setq foo (1+ foo)) + => 5 + + Now that the `cl' package is always available from lisp code, a + more convenient and natural way to increment a variable is + `(incf foo)'. + + -- Function: 1- number + This function returns NUMBER minus one. NUMBER may be a number, + character or marker. Markers and characters are converted to + integers. + + -- Function: abs number + This returns the absolute value of NUMBER. + + -- Function: + &rest numbers + This function adds its arguments together. When given no + arguments, `+' returns 0. + + If any of the arguments are characters or markers, they are first + converted to integers. + + (+) + => 0 + (+ 1) + => 1 + (+ 1 2 3 4) + => 10 + + -- Function: - &optional number &rest other-numbers + The `-' function serves two purposes: negation and subtraction. + When `-' has a single argument, the value is the negative of the + argument. When there are multiple arguments, `-' subtracts each of + the OTHER-NUMBERS from NUMBER, cumulatively. If there are no + arguments, an error is signaled. + + If any of the arguments are characters or markers, they are first + converted to integers. + + (- 10 1 2 3 4) + => 0 + (- 10) + => -10 + (-) + => 0 + + -- Function: * &rest numbers + This function multiplies its arguments together, and returns the + product. When given no arguments, `*' returns 1. + + If any of the arguments are characters or markers, they are first + converted to integers. + + (*) + => 1 + (* 1) + => 1 + (* 1 2 3 4) + => 24 + + -- Function: / dividend &rest divisors + The `/' function serves two purposes: inversion and division. When + `/' has a single argument, the value is the inverse of the + argument. When there are multiple arguments, `/' divides DIVIDEND + by each of the DIVISORS, cumulatively, returning the quotient. If + there are no arguments, an error is signaled. + + If none of the arguments are floats, then the result is an integer. + This means the result has to be rounded. On most machines, the + result is rounded towards zero after each division, but some + machines may round differently with negative arguments. This is + because the Lisp function `/' is implemented using the C division + operator, which also permits machine-dependent rounding. As a + practical matter, all known machines round in the standard fashion. + + If any of the arguments are characters or markers, they are first + converted to integers. + + If you divide by 0, an `arith-error' error is signaled. (*Note + Errors::.) + + (/ 6 2) + => 3 + (/ 5 2) + => 2 + (/ 25 3 2) + => 4 + (/ 3.0) + => 0.3333333333333333 + (/ -17 6) + => -2 + + The result of `(/ -17 6)' could in principle be -3 on some + machines. + + -- Function: % dividend divisor + This function returns the integer remainder after division of + DIVIDEND by DIVISOR. The arguments must be integers or markers. + + For negative arguments, the remainder is in principle + machine-dependent since the quotient is; but in practice, all + known machines behave alike. + + An `arith-error' results if DIVISOR is 0. + + (% 9 4) + => 1 + (% -9 4) + => -1 + (% 9 -4) + => 1 + (% -9 -4) + => -1 + + For any two integers DIVIDEND and DIVISOR, + + (+ (% DIVIDEND DIVISOR) + (* (/ DIVIDEND DIVISOR) DIVISOR)) + + always equals DIVIDEND. + + -- Function: mod dividend divisor + This function returns the value of DIVIDEND modulo DIVISOR; in + other words, the remainder after division of DIVIDEND by DIVISOR, + but with the same sign as DIVISOR. The arguments must be numbers + or markers. + + Unlike `%', `mod' returns a well-defined result for negative + arguments. It also permits floating point arguments; it rounds the + quotient downward (towards minus infinity) to an integer, and uses + that quotient to compute the remainder. + + An `arith-error' results if DIVISOR is 0. + + (mod 9 4) + => 1 + (mod -9 4) + => 3 + (mod 9 -4) + => -3 + (mod -9 -4) + => -1 + (mod 5.5 2.5) + => .5 + + For any two numbers DIVIDEND and DIVISOR, + + (+ (mod DIVIDEND DIVISOR) + (* (floor DIVIDEND DIVISOR) DIVISOR)) + + always equals DIVIDEND, subject to rounding error if either + argument is floating point. For `floor', see *Note Numeric + Conversions::. + + +File: lispref.info, Node: Rounding Operations, Next: Bitwise Operations, Prev: Arithmetic Operations, Up: Numbers + +9.7 Rounding Operations +======================= + +The functions `ffloor', `fceiling', `fround' and `ftruncate' take a +floating point argument and return a floating point result whose value +is a nearby integer. `ffloor' returns the nearest integer below; +`fceiling', the nearest integer above; `ftruncate', the nearest integer +in the direction towards zero; `fround', the nearest integer. + + -- Function: ffloor number + This function rounds NUMBER to the next lower integral value, and + returns that value as a floating point number. + + -- Function: fceiling number + This function rounds NUMBER to the next higher integral value, and + returns that value as a floating point number. + + -- Function: ftruncate number + This function rounds NUMBER towards zero to an integral value, and + returns that value as a floating point number. + + -- Function: fround number + This function rounds NUMBER to the nearest integral value, and + returns that value as a floating point number. + + +File: lispref.info, Node: Bitwise Operations, Next: Math Functions, Prev: Rounding Operations, Up: Numbers + +9.8 Bitwise Operations on Integers +================================== + +In a computer, an integer is represented as a binary number, a sequence +of "bits" (digits which are either zero or one). A bitwise operation +acts on the individual bits of such a sequence. For example, +"shifting" moves the whole sequence left or right one or more places, +reproducing the same pattern "moved over". + + The bitwise operations in XEmacs Lisp apply only to integers. + + -- Function: lsh integer1 count + `lsh', which is an abbreviation for "logical shift", shifts the + bits in INTEGER1 to the left COUNT places, or to the right if + COUNT is negative, bringing zeros into the vacated bits. If COUNT + is negative, `lsh' shifts zeros into the leftmost + (most-significant) bit, producing a positive result even if + INTEGER1 is negative. Contrast this with `ash', below. + + Here are two examples of `lsh', shifting a pattern of bits one + place to the left. We show only the low-order eight bits of the + binary pattern; the rest are all zero. + + (lsh 5 1) + => 10 + ;; Decimal 5 becomes decimal 10. + 00000101 => 00001010 + + (lsh 7 1) + => 14 + ;; Decimal 7 becomes decimal 14. + 00000111 => 00001110 + + As the examples illustrate, shifting the pattern of bits one place + to the left produces a number that is twice the value of the + previous number. + + Shifting a pattern of bits two places to the left produces results + like this (with 8-bit binary numbers): + + (lsh 3 2) + => 12 + ;; Decimal 3 becomes decimal 12. + 00000011 => 00001100 + + On the other hand, shifting one place to the right looks like this: + + (lsh 6 -1) + => 3 + ;; Decimal 6 becomes decimal 3. + 00000110 => 00000011 + + (lsh 5 -1) + => 2 + ;; Decimal 5 becomes decimal 2. + 00000101 => 00000010 + + As the example illustrates, shifting one place to the right + divides the value of a positive integer by two, rounding downward. + + The function `lsh', like all XEmacs Lisp arithmetic functions, does + not check for overflow, so shifting left can discard significant + bits and change the sign of the number. For example, left shifting + 134,217,727 produces -2 on a 28-bit machine: + + (lsh 134217727 1) ; left shift + => -2 + + In binary, in the 28-bit implementation, the argument looks like + this: + + ;; Decimal 134,217,727 + 0111 1111 1111 1111 1111 1111 1111 + + which becomes the following when left shifted: + + ;; Decimal -2 + 1111 1111 1111 1111 1111 1111 1110 + + -- Function: ash integer1 count + `ash' ("arithmetic shift") shifts the bits in INTEGER1 to the left + COUNT places, or to the right if COUNT is negative. + + `ash' gives the same results as `lsh' except when INTEGER1 and + COUNT are both negative. In that case, `ash' puts ones in the + empty bit positions on the left, while `lsh' puts zeros in those + bit positions. + + Thus, with `ash', shifting the pattern of bits one place to the + right looks like this: + + (ash -6 -1) => -3 + ;; Decimal -6 becomes decimal -3. + 1111 1111 1111 1111 1111 1111 1010 + => + 1111 1111 1111 1111 1111 1111 1101 + + In contrast, shifting the pattern of bits one place to the right + with `lsh' looks like this: + + (lsh -6 -1) => 134217725 + ;; Decimal -6 becomes decimal 134,217,725. + 1111 1111 1111 1111 1111 1111 1010 + => + 0111 1111 1111 1111 1111 1111 1101 + + Here are other examples: + + ; 28-bit binary values + + (lsh 5 2) ; 5 = 0000 0000 0000 0000 0000 0000 0101 + => 20 ; = 0000 0000 0000 0000 0000 0001 0100 + (ash 5 2) + => 20 + (lsh -5 2) ; -5 = 1111 1111 1111 1111 1111 1111 1011 + => -20 ; = 1111 1111 1111 1111 1111 1110 1100 + (ash -5 2) + => -20 + (lsh 5 -2) ; 5 = 0000 0000 0000 0000 0000 0000 0101 + => 1 ; = 0000 0000 0000 0000 0000 0000 0001 + (ash 5 -2) + => 1 + (lsh -5 -2) ; -5 = 1111 1111 1111 1111 1111 1111 1011 + => 4194302 ; = 0011 1111 1111 1111 1111 1111 1110 + (ash -5 -2) ; -5 = 1111 1111 1111 1111 1111 1111 1011 + => -2 ; = 1111 1111 1111 1111 1111 1111 1110 + + -- Function: logand &rest ints-or-markers + This function returns the "logical and" of the arguments: the Nth + bit is set in the result if, and only if, the Nth bit is set in + all the arguments. ("Set" means that the value of the bit is 1 + rather than 0.) + + For example, using 4-bit binary numbers, the "logical and" of 13 + and 12 is 12: 1101 combined with 1100 produces 1100. In both the + binary numbers, the leftmost two bits are set (i.e., they are + 1's), so the leftmost two bits of the returned value are set. + However, for the rightmost two bits, each is zero in at least one + of the arguments, so the rightmost two bits of the returned value + are 0's. + + Therefore, + + (logand 13 12) + => 12 + + If `logand' is not passed any argument, it returns a value of -1. + This number is an identity element for `logand' because its binary + representation consists entirely of ones. If `logand' is passed + just one argument, it returns that argument. + + ; 28-bit binary values + + (logand 14 13) ; 14 = 0000 0000 0000 0000 0000 0000 1110 + ; 13 = 0000 0000 0000 0000 0000 0000 1101 + => 12 ; 12 = 0000 0000 0000 0000 0000 0000 1100 + + (logand 14 13 4) ; 14 = 0000 0000 0000 0000 0000 0000 1110 + ; 13 = 0000 0000 0000 0000 0000 0000 1101 + ; 4 = 0000 0000 0000 0000 0000 0000 0100 + => 4 ; 4 = 0000 0000 0000 0000 0000 0000 0100 + + (logand) + => -1 ; -1 = 1111 1111 1111 1111 1111 1111 1111 + + -- Function: logior &rest ints-or-markers + This function returns the "inclusive or" of its arguments: the Nth + bit is set in the result if, and only if, the Nth bit is set in at + least one of the arguments. If there are no arguments, the result + is zero, which is an identity element for this operation. If + `logior' is passed just one argument, it returns that argument. + + ; 28-bit binary values + + (logior 12 5) ; 12 = 0000 0000 0000 0000 0000 0000 1100 + ; 5 = 0000 0000 0000 0000 0000 0000 0101 + => 13 ; 13 = 0000 0000 0000 0000 0000 0000 1101 + + (logior 12 5 7) ; 12 = 0000 0000 0000 0000 0000 0000 1100 + ; 5 = 0000 0000 0000 0000 0000 0000 0101 + ; 7 = 0000 0000 0000 0000 0000 0000 0111 + => 15 ; 15 = 0000 0000 0000 0000 0000 0000 1111 + + -- Function: logxor &rest ints-or-markers + This function returns the "exclusive or" of its arguments: the Nth + bit is set in the result if, and only if, the Nth bit is set in an + odd number of the arguments. If there are no arguments, the + result is 0, which is an identity element for this operation. If + `logxor' is passed just one argument, it returns that argument. + + ; 28-bit binary values + + (logxor 12 5) ; 12 = 0000 0000 0000 0000 0000 0000 1100 + ; 5 = 0000 0000 0000 0000 0000 0000 0101 + => 9 ; 9 = 0000 0000 0000 0000 0000 0000 1001 + + (logxor 12 5 7) ; 12 = 0000 0000 0000 0000 0000 0000 1100 + ; 5 = 0000 0000 0000 0000 0000 0000 0101 + ; 7 = 0000 0000 0000 0000 0000 0000 0111 + => 14 ; 14 = 0000 0000 0000 0000 0000 0000 1110 + + -- Function: lognot integer + This function returns the logical complement of its argument: the + Nth bit is one in the result if, and only if, the Nth bit is zero + in INTEGER, and vice-versa. + + (lognot 5) + => -6 + ;; 5 = 0000 0000 0000 0000 0000 0000 0101 + ;; becomes + ;; -6 = 1111 1111 1111 1111 1111 1111 1010 + + +File: lispref.info, Node: Math Functions, Next: Random Numbers, Prev: Bitwise Operations, Up: Numbers + +9.9 Standard Mathematical Functions +=================================== + +These mathematical functions are available if floating point is +supported (which is the normal state of affairs). They allow integers +as well as floating point numbers as arguments. + + -- Function: sin number + -- Function: cos number + -- Function: tan number + These are the ordinary trigonometric functions, with argument + measured in radians. + + -- Function: asin number + The value of `(asin NUMBER)' is a number between -pi/2 and pi/2 + (inclusive) whose sine is NUMBER; if, however, NUMBER is out of + range (outside [-1, 1]), then the result is a NaN. + + -- Function: acos number + The value of `(acos NUMBER)' is a number between 0 and pi + (inclusive) whose cosine is NUMBER; if, however, NUMBER is out of + range (outside [-1, 1]), then the result is a NaN. + + -- Function: atan number &optional number2 + The value of `(atan NUMBER)' is a number between -pi/2 and pi/2 + (exclusive) whose tangent is NUMBER. + + If optional argument NUMBER2 is supplied, the function returns + `atan2(NUMBER,NUMBER2)'. + + -- Function: sinh number + -- Function: cosh number + -- Function: tanh number + These are the ordinary hyperbolic trigonometric functions. + + -- Function: asinh number + -- Function: acosh number + -- Function: atanh number + These are the inverse hyperbolic trigonometric functions. + + -- Function: exp number + This is the exponential function; it returns e to the power + NUMBER. e is a fundamental mathematical constant also called the + base of natural logarithms. + + -- Function: log number &optional base + This function returns the logarithm of NUMBER, with base BASE. If + you don't specify BASE, the base `e' is used. If NUMBER is + negative, the result is a NaN. + + -- Function: log10 number + This function returns the logarithm of NUMBER, with base 10. If + NUMBER is negative, the result is a NaN. `(log10 X)' == `(log X + 10)', at least approximately. + + -- Function: expt x y + This function returns X raised to power Y. If both arguments are + integers and Y is positive, the result is an integer; in this + case, it is truncated to fit the range of possible integer values. + + -- Function: sqrt number + This returns the square root of NUMBER. If NUMBER is negative, + the value is a NaN. + + -- Function: cube-root number + This returns the cube root of NUMBER. + + +File: lispref.info, Node: Random Numbers, Prev: Math Functions, Up: Numbers + +9.10 Random Numbers +=================== + +A deterministic computer program cannot generate true random numbers. +For most purposes, "pseudo-random numbers" suffice. A series of +pseudo-random numbers is generated in a deterministic fashion. The +numbers are not truly random, but they have certain properties that +mimic a random series. For example, all possible values occur equally +often in a pseudo-random series. + + In XEmacs, pseudo-random numbers are generated from a "seed" number. +Starting from any given seed, the `random' function always generates +the same sequence of numbers. XEmacs always starts with the same seed +value, so the sequence of values of `random' is actually the same in +each XEmacs run! For example, in one operating system, the first call +to `(random)' after you start XEmacs always returns -1457731, and the +second one always returns -7692030. This repeatability is helpful for +debugging. + + If you want truly unpredictable random numbers, execute `(random +t)'. This chooses a new seed based on the current time of day and on +XEmacs's process ID number. + + -- Function: random &optional limit + This function returns a pseudo-random integer. Repeated calls + return a series of pseudo-random integers. + + If LIMIT is a positive integer, the value is chosen to be + nonnegative and less than LIMIT. + + If LIMIT is `t', it means to choose a new seed based on the + current time of day and on XEmacs's process ID number. + + On some machines, any integer representable in Lisp may be the + result of `random'. On other machines, the result can never be + larger than a certain maximum or less than a certain (negative) + minimum. + + +File: lispref.info, Node: Strings and Characters, Next: Lists, Prev: Numbers, Up: Top + +10 Strings and Characters +************************* + +A string in XEmacs Lisp is an array that contains an ordered sequence +of characters. Strings are used as names of symbols, buffers, and +files, to send messages to users, to hold text being copied between +buffers, and for many other purposes. Because strings are so important, +XEmacs Lisp has many functions expressly for manipulating them. XEmacs +Lisp programs use strings more often than individual characters. + +* Menu: + +* String Basics:: Basic properties of strings and characters. +* Predicates for Strings:: Testing whether an object is a string or char. +* Creating Strings:: Functions to allocate new strings. +* Predicates for Characters:: Testing whether an object is a character. +* Character Codes:: Each character has an equivalent integer. +* Text Comparison:: Comparing characters or strings. +* String Conversion:: Converting characters or strings and vice versa. +* Modifying Strings:: Changing characters in a string. +* String Properties:: Additional information attached to strings. +* Formatting Strings:: `format': XEmacs's analog of `printf'. +* Character Case:: Case conversion functions. +* Case Tables:: Customizing case conversion. +* Char Tables:: Mapping from characters to Lisp objects. + + +File: lispref.info, Node: String Basics, Next: Predicates for Strings, Up: Strings and Characters + +10.1 String and Character Basics +================================ + +Strings in XEmacs Lisp are arrays that contain an ordered sequence of +characters. Characters are their own primitive object type in XEmacs +20. However, in XEmacs 19, characters are represented in XEmacs Lisp as +integers; whether an integer was intended as a character or not is +determined only by how it is used. *Note Character Type::. + + The length of a string (like any array) is fixed and independent of +the string contents, and cannot be altered. Strings in Lisp are _not_ +terminated by a distinguished character code. (By contrast, strings in +C are terminated by a character with ASCII code 0.) This means that +any character, including the null character (ASCII code 0), is a valid +element of a string. + + Since strings are considered arrays, you can operate on them with the +general array functions. (*Note Sequences Arrays Vectors::.) For +example, you can access or change individual characters in a string +using the functions `aref' and `aset' (*note Array Functions::). + + Strings use an efficient representation for storing the characters +in them, and thus take up much less memory than a vector of the same +length. + + Sometimes you will see strings used to hold key sequences. This +exists for backward compatibility with Emacs 18, but should _not_ be +used in new code, since many key chords can't be represented at all and +others (in particular meta key chords) are confused with accented +characters. + + Strings are useful for holding regular expressions. You can also +match regular expressions against strings (*note Regexp Search::). The +functions `match-string' (*note Simple Match Data::) and +`replace-match' (*note Replacing Match::) are useful for decomposing +and modifying strings based on regular expression matching. + + Like a buffer, a string can contain extents in it. These extents are +created when a function such as `buffer-substring' is called on a +region with duplicable extents in it. When the string is inserted into +a buffer, the extents are inserted along with it. *Note Duplicable +Extents::. + + *Note Text::, for information about functions that display strings or +copy them into buffers. *Note Character Type::, and *Note String +Type::, for information about the syntax of characters and strings. + + +File: lispref.info, Node: Predicates for Strings, Next: Creating Strings, Prev: String Basics, Up: Strings and Characters + +10.2 The Predicates for Strings +=============================== + +For more information about general sequence and array predicates, see +*Note Sequences Arrays Vectors::, and *Note Arrays::. + + -- Function: stringp object + This function returns `t' if OBJECT is a string, `nil' otherwise. + + -- Function: char-or-string-p object + This function returns `t' if OBJECT is a string or a character, + `nil' otherwise. + + In XEmacs addition, this function also returns `t' if OBJECT is an + integer that can be represented as a character. This is because + of compatibility with previous XEmacs and should not be depended + on. + + +File: lispref.info, Node: Creating Strings, Next: Predicates for Characters, Prev: Predicates for Strings, Up: Strings and Characters + +10.3 Creating Strings +===================== + +The following functions create strings, either from scratch, or by +putting strings together, or by taking them apart. + + -- Function: string &rest characters + This function returns a new string made up of CHARACTERS. + + (string ?X ?E ?m ?a ?c ?s) + => "XEmacs" + (string) + => "" + + Analogous functions operating on other data types include `list', + `cons' (*note Building Lists::), `vector' (*note Vectors::) and + `bit-vector' (*note Bit Vectors::). This function has not been + available in XEmacs prior to 21.0 and FSF Emacs prior to 20.3. + + -- Function: make-string length character + This function returns a new string consisting entirely of LENGTH + successive copies of CHARACTER. LENGTH must be a non-negative + integer. + + (make-string 5 ?x) + => "xxxxx" + (make-string 0 ?x) + => "" + + Other functions to compare with this one include `char-to-string' + (*note String Conversion::), `make-vector' (*note Vectors::), and + `make-list' (*note Building Lists::). + + -- Function: substring string start &optional end + This function returns a new string which consists of those + characters from STRING in the range from (and including) the + character at the index START up to (but excluding) the character + at the index END. The first character is at index zero. + + (substring "abcdefg" 0 3) + => "abc" + + Here the index for `a' is 0, the index for `b' is 1, and the index + for `c' is 2. Thus, three letters, `abc', are copied from the + string `"abcdefg"'. The index 3 marks the character position up + to which the substring is copied. The character whose index is 3 + is actually the fourth character in the string. + + A negative number counts from the end of the string, so that -1 + signifies the index of the last character of the string. For + example: + + (substring "abcdefg" -3 -1) + => "ef" + + In this example, the index for `e' is -3, the index for `f' is -2, + and the index for `g' is -1. Therefore, `e' and `f' are included, + and `g' is excluded. + + When `nil' is used as an index, it stands for the length of the + string. Thus, + + (substring "abcdefg" -3 nil) + => "efg" + + Omitting the argument END is equivalent to specifying `nil'. It + follows that `(substring STRING 0)' returns a copy of all of + STRING. + + (substring "abcdefg" 0) + => "abcdefg" + + But we recommend `copy-sequence' for this purpose (*note Sequence + Functions::). + + If the characters copied from STRING have duplicable extents or + text properties, those are copied into the new string also. *Note + Duplicable Extents::. + + A `wrong-type-argument' error is signaled if either START or END + is not an integer or `nil'. An `args-out-of-range' error is + signaled if START indicates a character following END, or if + either integer is out of range for STRING. + + Contrast this function with `buffer-substring' (*note Buffer + Contents::), which returns a string containing a portion of the + text in the current buffer. The beginning of a string is at index + 0, but the beginning of a buffer is at index 1. + + -- Function: concat &rest sequences + This function returns a new string consisting of the characters in + the arguments passed to it (along with their text properties, if + any). The arguments may be strings, lists of numbers, or vectors + of numbers; they are not themselves changed. If `concat' receives + no arguments, it returns an empty string. + + (concat "abc" "-def") + => "abc-def" + (concat "abc" (list 120 (+ 256 121)) [122]) + => "abcxyz" + ;; `nil' is an empty sequence. + (concat "abc" nil "-def") + => "abc-def" + (concat "The " "quick brown " "fox.") + => "The quick brown fox." + (concat) + => "" + + The second example above shows how characters stored in strings are + taken modulo 256. In other words, each character in the string is + stored in one byte. + + The `concat' function always constructs a new string that is not + `eq' to any existing string. + + When an argument is an integer (not a sequence of integers), it is + converted to a string of digits making up the decimal printed + representation of the integer. *Don't use this feature; we plan + to eliminate it. If you already use this feature, change your + programs now!* The proper way to convert an integer to a decimal + number in this way is with `format' (*note Formatting Strings::) or + `number-to-string' (*note String Conversion::). + + (concat 137) + => "137" + (concat 54 321) + => "54321" + + For information about other concatenation functions, see the + description of `mapconcat' in *Note Mapping Functions::, `vconcat' + in *Note Vectors::, `bvconcat' in *Note Bit Vectors::, and `append' + in *Note Building Lists::. + + +File: lispref.info, Node: Predicates for Characters, Next: Character Codes, Prev: Creating Strings, Up: Strings and Characters + +10.4 The Predicates for Characters +================================== + + -- Function: characterp object + This function returns `t' if OBJECT is a character. + + Some functions that work on integers (e.g. the comparison functions + <, <=, =, /=, etc. and the arithmetic functions +, -, *, etc.) + accept characters and implicitly convert them into integers. In + general, functions that work on characters also accept char-ints + and implicitly convert them into characters. WARNING: Neither of + these behaviors is very desirable, and they are maintained for + backward compatibility with old E-Lisp programs that confounded + characters and integers willy-nilly. These behaviors may change + in the future; therefore, do not rely on them. Instead, convert + the characters explicitly using `char-int'. + + -- Function: integer-or-char-p object + This function returns `t' if OBJECT is an integer or character. + + +File: lispref.info, Node: Character Codes, Next: Text Comparison, Prev: Predicates for Characters, Up: Strings and Characters + +10.5 Character Codes +==================== + + -- Function: char-int character + This function converts a character into an equivalent integer. + The resulting integer will always be non-negative. The integers in + the range 0 - 255 map to characters as follows: + + 0 - 31 + Control set 0 + + 32 - 127 + ASCII + + 128 - 159 + Control set 1 + + 160 - 255 + Right half of ISO-8859-1 + + If support for MULE does not exist, these are the only valid + character values. When MULE support exists, the values assigned to + other characters may vary depending on the particular version of + XEmacs, the order in which character sets were loaded, etc., and + you should not depend on them. + + -- Function: int-char integer + This function converts an integer into the equivalent character. + Not all integers correspond to valid characters; use `char-int-p' + to determine whether this is the case. If the integer cannot be + converted, `nil' is returned. + + -- Function: char-int-p object + This function returns `t' if OBJECT is an integer that can be + converted into a character. + + -- Function: char-or-char-int-p object + This function returns `t' if OBJECT is a character or an integer + that can be converted into one. + + +File: lispref.info, Node: Text Comparison, Next: String Conversion, Prev: Character Codes, Up: Strings and Characters + +10.6 Comparison of Characters and Strings +========================================= + + -- Function: char-equal character1 character2 &optional buffer + This function returns `t' if the arguments represent the same + character, `nil' otherwise. This function ignores differences in + case if the value of `case-fold-search' is non-`nil' in BUFFER, + which defaults to the current buffer. + + (char-equal ?x ?x) + => t + (let ((case-fold-search t)) + (char-equal ?x ?X)) + => t + (let ((case-fold-search nil)) + (char-equal ?x ?X)) + => nil + + -- Function: char= character1 character2 + This function returns `t' if the arguments represent the same + character, `nil' otherwise. Case is significant. + + (char= ?x ?x) + => t + (char= ?x ?X) + => nil + (let ((case-fold-search t)) + (char-equal ?x ?X)) + => nil + (let ((case-fold-search nil)) + (char-equal ?x ?X)) + => nil + + -- Function: string= string1 string2 + This function returns `t' if the characters of the two strings + match exactly; case is significant. + + (string= "abc" "abc") + => t + (string= "abc" "ABC") + => nil + (string= "ab" "ABC") + => nil + + + -- Function: string-equal string1 string2 + `string-equal' is another name for `string='. + + -- Function: string< string1 string2 + This function compares two strings a character at a time. First it + scans both the strings at once to find the first pair of + corresponding characters that do not match. If the lesser + character of those two is the character from STRING1, then STRING1 + is less, and this function returns `t'. If the lesser character + is the one from STRING2, then STRING1 is greater, and this + function returns `nil'. If the two strings match entirely, the + value is `nil'. + + Pairs of characters are compared by their ASCII codes. Keep in + mind that lower case letters have higher numeric values in the + ASCII character set than their upper case counterparts; numbers and + many punctuation characters have a lower numeric value than upper + case letters. + + (string< "abc" "abd") + => t + (string< "abd" "abc") + => nil + (string< "123" "abc") + => t + + When the strings have different lengths, and they match up to the + length of STRING1, then the result is `t'. If they match up to + the length of STRING2, the result is `nil'. A string of no + characters is less than any other string. + + (string< "" "abc") + => t + (string< "ab" "abc") + => t + (string< "abc" "") + => nil + (string< "abc" "ab") + => nil + (string< "" "") + => nil + + -- Function: string-lessp string1 string2 + `string-lessp' is another name for `string<'. + + See also `compare-buffer-substrings' in *Note Comparing Text::, for +a way to compare text in buffers. The function `string-match', which +matches a regular expression against a string, can be used for a kind +of string comparison; see *Note Regexp Search::. + + +File: lispref.info, Node: String Conversion, Next: Modifying Strings, Prev: Text Comparison, Up: Strings and Characters + +10.7 Conversion of Characters and Strings +========================================= + +This section describes functions for conversions between characters, +strings and integers. `format' and `prin1-to-string' (*note Output +Functions::) can also convert Lisp objects into strings. +`read-from-string' (*note Input Functions::) can "convert" a string +representation of a Lisp object into an object. + + *Note Documentation::, for functions that produce textual +descriptions of text characters and general input events +(`single-key-description' and `text-char-description'). These +functions are used primarily for making help messages. + + -- Function: char-to-string character + This function returns a new string with a length of one character. + The value of CHARACTER, modulo 256, is used to initialize the + element of the string. + + This function is similar to `make-string' with an integer argument + of 1. (*Note Creating Strings::.) This conversion can also be + done with `format' using the `%c' format specification. (*Note + Formatting Strings::.) + + (char-to-string ?x) + => "x" + (char-to-string (+ 256 ?x)) + => "x" + (make-string 1 ?x) + => "x" + + -- Function: string-to-char string + This function returns the first character in STRING. If the + string is empty, the function returns 0. (Under XEmacs 19, the + value is also 0 when the first character of STRING is the null + character, ASCII code 0.) + + (string-to-char "ABC") + => ?A ;; Under XEmacs 20. + => 65 ;; Under XEmacs 19. + (string-to-char "xyz") + => ?x ;; Under XEmacs 20. + => 120 ;; Under XEmacs 19. + (string-to-char "") + => 0 + (string-to-char "\000") + => ?\^ ;; Under XEmacs 20. + => 0 ;; Under XEmacs 20. + + This function may be eliminated in the future if it does not seem + useful enough to retain. + + -- Function: number-to-string number + This function returns a string consisting of the printed + representation of NUMBER, which may be an integer or a floating + point number. The value starts with a sign if the argument is + negative. + + (number-to-string 256) + => "256" + (number-to-string -23) + => "-23" + (number-to-string -23.5) + => "-23.5" + + `int-to-string' is a semi-obsolete alias for this function. + + See also the function `format' in *Note Formatting Strings::. + + -- Function: string-to-number string &optional base + This function returns the numeric value represented by STRING, + read in BASE. It skips spaces and tabs at the beginning of + STRING, then reads as much of STRING as it can interpret as a + number. (On some systems it ignores other whitespace at the + beginning, not just spaces and tabs.) If the first character + after the ignored whitespace is not a digit or a minus sign, this + function returns 0. + + If BASE is not specified, it defaults to ten. With BASE other + than ten, only integers can be read. + + (string-to-number "256") + => 256 + (string-to-number "25 is a perfect square.") + => 25 + (string-to-number "X256") + => 0 + (string-to-number "-4.5") + => -4.5 + (string-to-number "ffff" 16) + => 65535 + + `string-to-int' is an obsolete alias for this function. + + +File: lispref.info, Node: Modifying Strings, Next: String Properties, Prev: String Conversion, Up: Strings and Characters + +10.8 Modifying Strings +====================== + +You can modify a string using the general array-modifying primitives. +*Note Arrays::. The function `aset' modifies a single character; the +function `fillarray' sets all characters in the string to a specified +character. + + Each string has a tick counter that starts out at zero (when the +string is created) and is incremented each time a change is made to that +string. + + -- Function: string-modified-tick string + This function returns the tick counter for `string'. + + +File: lispref.info, Node: String Properties, Next: Formatting Strings, Prev: Modifying Strings, Up: Strings and Characters + +10.9 String Properties +====================== + +Just as with symbols, extents, faces, and glyphs, you can attach +additional information to strings in the form of "string properties". +These differ from text properties, which are logically attached to +particular characters in the string. + + To attach a property to a string, use `put'. To retrieve a property +from a string, use `get'. You can also use `remprop' to remove a +property from a string and `object-plist' to retrieve a list of all the +properties in a string. + + +File: lispref.info, Node: Formatting Strings, Next: Character Case, Prev: String Properties, Up: Strings and Characters + +10.10 Formatting Strings +======================== + +"Formatting" means constructing a string by substitution of computed +values at various places in a constant string. This string controls +how the other values are printed as well as where they appear; it is +called a "format string". + + Formatting is often useful for computing messages to be displayed. +In fact, the functions `message' and `error' provide the same +formatting feature described here; they differ from `format' only in +how they use the result of formatting. + + -- Function: format string &rest objects + This function returns a new string that is made by copying STRING + and then replacing any format specification in the copy with + encodings of the corresponding OBJECTS. The arguments OBJECTS are + the computed values to be formatted. + + A format specification is a sequence of characters beginning with a +`%'. Thus, if there is a `%d' in STRING, the `format' function +replaces it with the printed representation of one of the values to be +formatted (one of the arguments OBJECTS). For example: + + (format "The value of fill-column is %d." fill-column) + => "The value of fill-column is 72." + + If STRING contains more than one format specification, the format +specifications correspond with successive values from OBJECTS. Thus, +the first format specification in STRING uses the first such value, the +second format specification uses the second such value, and so on. Any +extra format specifications (those for which there are no corresponding +values) cause unpredictable behavior. Any extra values to be formatted +are ignored. + + Certain format specifications require values of particular types. +However, no error is signaled if the value actually supplied fails to +have the expected type. Instead, the output is likely to be +meaningless. + + Here is a table of valid format specifications: + +`%s' + Replace the specification with the printed representation of the + object, made without quoting. Thus, strings are represented by + their contents alone, with no `"' characters, and symbols appear + without `\' characters. This is equivalent to printing the object + with `princ'. + + If there is no corresponding object, the empty string is used. + +`%S' + Replace the specification with the printed representation of the + object, made with quoting. Thus, strings are enclosed in `"' + characters, and `\' characters appear where necessary before + special characters. This is equivalent to printing the object + with `prin1'. + + If there is no corresponding object, the empty string is used. + +`%o' + Replace the specification with the base-eight representation of an + integer. + +`%d' +`%i' + Replace the specification with the base-ten representation of an + integer. + +`%x' + Replace the specification with the base-sixteen representation of + an integer, using lowercase letters. + +`%X' + Replace the specification with the base-sixteen representation of + an integer, using uppercase letters. + +`%c' + Replace the specification with the character which is the value + given. + +`%e' + Replace the specification with the exponential notation for a + floating point number (e.g. `7.85200e+03'). + +`%f' + Replace the specification with the decimal-point notation for a + floating point number. + +`%g' + Replace the specification with notation for a floating point + number, using a "pretty format". Either exponential notation or + decimal-point notation will be used (usually whichever is + shorter), and trailing zeroes are removed from the fractional part. + +`%%' + A single `%' is placed in the string. This format specification is + unusual in that it does not use a value. For example, `(format "%% + %d" 30)' returns `"% 30"'. + + Any other format character results in an `Invalid format operation' +error. + + Here are several examples: + + (format "The name of this buffer is %s." (buffer-name)) + => "The name of this buffer is strings.texi." + + (format "The buffer object prints as %s." (current-buffer)) + => "The buffer object prints as #." + + (format "The octal value of %d is %o, + and the hex value is %x." 18 18 18) + => "The octal value of 18 is 22, + and the hex value is 12." + + There are many additional flags and specifications that can occur +between the `%' and the format character, in the following order: + + 1. An optional repositioning specification, which is a positive + integer followed by a `$'. + + 2. Zero or more of the optional flag characters `-', `+', ` ', `0', + and `#'. + + 3. An asterisk (`*', meaning that the field width is now assumed to + have been specified as an argument. + + 4. An optional minimum field width. + + 5. An optional precision, preceded by a `.' character. + + A "repositioning" specification changes which argument to `format' +is used by the current and all following format specifications. +Normally the first specification uses the first argument, the second +specification uses the second argument, etc. Using a repositioning +specification, you can change this. By placing a number N followed by +a `$' between the `%' and the format character, you cause the +specification to use the Nth argument. The next specification will use +the N+1'th argument, etc. + + For example: + + (format "Can't find file `%s' in directory `%s'." + "ignatius.c" "loyola/") + => "Can't find file `ignatius.c' in directory `loyola/'." + + (format "In directory `%2$s', the file `%1$s' was not found." + "ignatius.c" "loyola/") + => "In directory `loyola/', the file `ignatius.c' was not found." + + (format + "The numbers %d and %d are %1$x and %x in hex and %1$o and %o in octal." + 37 12) + => "The numbers 37 and 12 are 25 and c in hex and 45 and 14 in octal." + + As you can see, this lets you reprocess arguments more than once or +reword a format specification (thereby moving the arguments around) +without having to actually reorder the arguments. This is especially +useful in translating messages from one language to another: Different +languages use different word orders, and this sometimes entails changing +the order of the arguments. By using repositioning specifications, +this can be accomplished without having to embed knowledge of particular +languages into the location in the program's code where the message is +displayed. + + All the specification characters allow an optional numeric prefix +between the `%' and the character, and following any repositioning +specification or flag. The optional numeric prefix defines the minimum +width for the object. If the printed representation of the object +contains fewer characters than this, then it is padded. The padding is +normally on the left, but will be on the right if the `-' flag +character is given. The padding character is normally a space, but if +the `0' flag character is given, zeros are used for padding. + + (format "%06d is padded on the left with zeros" 123) + => "000123 is padded on the left with zeros" + + (format "%-6d is padded on the right" 123) + => "123 is padded on the right" + + `format' never truncates an object's printed representation, no +matter what width you specify. Thus, you can use a numeric prefix to +specify a minimum spacing between columns with no risk of losing +information. + + In the following three examples, `%7s' specifies a minimum width of +7. In the first case, the string inserted in place of `%7s' has only 3 +letters, so 4 blank spaces are inserted for padding. In the second +case, the string `"specification"' is 13 letters wide but is not +truncated. In the third case, the padding is on the right. + + (format "The word `%7s' actually has %d letters in it." + "foo" (length "foo")) + => "The word ` foo' actually has 3 letters in it." + + (format "The word `%7s' actually has %d letters in it." + "specification" (length "specification")) + => "The word `specification' actually has 13 letters in it." + + (format "The word `%-7s' actually has %d letters in it." + "foo" (length "foo")) + => "The word `foo ' actually has 3 letters in it." + + After any minimum field width, a precision may be specified by +preceding it with a `.' character. The precision specifies the minimum +number of digits to appear in `%d', `%i', `%o', `%x', and `%X' +conversions (the number is padded on the left with zeroes as +necessary); the number of digits printed after the decimal point for +`%f', `%e', and `%E' conversions; the number of significant digits +printed in `%g' and `%G' conversions; and the maximum number of +non-padding characters printed in `%s' and `%S' conversions. The +default precision for floating-point conversions is six. + + The other flag characters have the following meanings: + + * The ` ' flag means prefix non-negative numbers with a space. + + * The `+' flag means prefix non-negative numbers with a plus sign. + + * The `#' flag means print numbers in an alternate, more verbose + format: octal numbers begin with zero; hex numbers begin with a + `0x' or `0X'; a decimal point is printed in `%f', `%e', and `%E' + conversions even if no numbers are printed after it; and trailing + zeroes are not omitted in `%g' and `%G' conversions. + + +File: lispref.info, Node: Character Case, Next: Case Tables, Prev: Formatting Strings, Up: Strings and Characters + +10.11 Character Case +==================== + +The character case functions change the case of single characters or of +the contents of strings. The functions convert only alphabetic +characters (the letters `A' through `Z' and `a' through `z'); other +characters are not altered. The functions do not modify the strings +that are passed to them as arguments. + + The examples below use the characters `X' and `x' which have ASCII +codes 88 and 120 respectively. + + -- Function: downcase string-or-char &optional buffer + This function converts a character or a string to lower case. + + When the argument to `downcase' is a string, the function creates + and returns a new string in which each letter in the argument that + is upper case is converted to lower case. When the argument to + `downcase' is a character, `downcase' returns the corresponding + lower case character. (This value is actually an integer under + XEmacs 19.) If the original character is lower case, or is not a + letter, then the value equals the original character. + + Optional second arg BUFFER specifies which buffer's case tables to + use, and defaults to the current buffer. + + (downcase "The cat in the hat") + => "the cat in the hat" + + (downcase ?X) + => ?x ;; Under XEmacs 20. + => 120 ;; Under XEmacs 19. + + -- Function: upcase string-or-char &optional buffer + This function converts a character or a string to upper case. + + When the argument to `upcase' is a string, the function creates + and returns a new string in which each letter in the argument that + is lower case is converted to upper case. + + When the argument to `upcase' is a character, `upcase' returns the + corresponding upper case character. (This value is actually an + integer under XEmacs 19.) If the original character is upper + case, or is not a letter, then the value equals the original + character. + + Optional second arg BUFFER specifies which buffer's case tables to + use, and defaults to the current buffer. + + (upcase "The cat in the hat") + => "THE CAT IN THE HAT" + + (upcase ?x) + => ?X ;; Under XEmacs 20. + => 88 ;; Under XEmacs 19. + + -- Function: capitalize string-or-char &optional buffer + This function capitalizes strings or characters. If + STRING-OR-CHAR is a string, the function creates and returns a new + string, whose contents are a copy of STRING-OR-CHAR in which each + word has been capitalized. This means that the first character of + each word is converted to upper case, and the rest are converted + to lower case. + + The definition of a word is any sequence of consecutive characters + that are assigned to the word constituent syntax class in the + current syntax table (*note Syntax Class Table::). + + When the argument to `capitalize' is a character, `capitalize' has + the same result as `upcase'. + + Optional second arg BUFFER specifies which buffer's case tables to + use, and defaults to the current buffer. + + (capitalize "The cat in the hat") + => "The Cat In The Hat" + + (capitalize "THE 77TH-HATTED CAT") + => "The 77th-Hatted Cat" + + (capitalize ?x) + => ?X ;; Under XEmacs 20. + => 88 ;; Under XEmacs 19. + + +File: lispref.info, Node: Case Tables, Next: Char Tables, Prev: Character Case, Up: Strings and Characters + +10.12 The Case Table +==================== + +You can customize case conversion by installing a special "case table". +A case table specifies the mapping between upper case and lower case +letters. It affects both the string and character case conversion +functions (see the previous section) and those that apply to text in the +buffer (*note Case Changes::). You need a case table if you are using a +language which has letters other than the standard ASCII letters. + + A case table is a list of this form: + + (DOWNCASE UPCASE CANONICALIZE EQUIVALENCES) + +where each element is either `nil' or a string of length 256. The +element DOWNCASE says how to map each character to its lower-case +equivalent. The element UPCASE maps each character to its upper-case +equivalent. If lower and upper case characters are in one-to-one +correspondence, use `nil' for UPCASE; then XEmacs deduces the upcase +table from DOWNCASE. + + For some languages, upper and lower case letters are not in +one-to-one correspondence. There may be two different lower case +letters with the same upper case equivalent. In these cases, you need +to specify the maps for both directions. + + The element CANONICALIZE maps each character to a canonical +equivalent; any two characters that are related by case-conversion have +the same canonical equivalent character. + + The element EQUIVALENCES is a map that cyclicly permutes each +equivalence class (of characters with the same canonical equivalent). +(For ordinary ASCII, this would map `a' into `A' and `A' into `a', and +likewise for each set of equivalent characters.) + + When you construct a case table, you can provide `nil' for +CANONICALIZE; then Emacs fills in this string from UPCASE and DOWNCASE. +You can also provide `nil' for EQUIVALENCES; then Emacs fills in this +string from CANONICALIZE. In a case table that is actually in use, +those components are non-`nil'. Do not try to specify EQUIVALENCES +without also specifying CANONICALIZE. + + Each buffer has a case table. XEmacs also has a "standard case +table" which is copied into each buffer when you create the buffer. +Changing the standard case table doesn't affect any existing buffers. + + Here are the functions for working with case tables: + + -- Function: case-table-p object + This predicate returns non-`nil' if OBJECT is a valid case table. + + -- Function: set-standard-case-table case-table + This function makes CASE-TABLE the standard case table, so that it + will apply to any buffers created subsequently. + + -- Function: standard-case-table + This returns the standard case table. + + -- Function: current-case-table &optional buffer + This function returns the case table of BUFFER, which defaults to + the current buffer. + + -- Function: set-case-table case-table + This sets the current buffer's case table to CASE-TABLE. + + The following three functions are convenient subroutines for packages +that define non-ASCII character sets. They modify a string +DOWNCASE-TABLE provided as an argument; this should be a string to be +used as the DOWNCASE part of a case table. They also modify the +standard syntax table. *Note Syntax Tables::. + + -- Function: set-case-syntax-pair uc lc downcase-table + This function specifies a pair of corresponding letters, one upper + case and one lower case. + + -- Function: set-case-syntax-delims l r downcase-table + This function makes characters L and R a matching pair of + case-invariant delimiters. + + -- Function: set-case-syntax char syntax downcase-table + This function makes CHAR case-invariant, with syntax SYNTAX. + + -- Command: describe-buffer-case-table + This command displays a description of the contents of the current + buffer's case table. + + You can load the library `iso-syntax' to set up the standard syntax +table and define a case table for the 8-bit ISO Latin 1 character set. + + +File: lispref.info, Node: Char Tables, Prev: Case Tables, Up: Strings and Characters + +10.13 The Char Table +==================== + +A char table is a table that maps characters (or ranges of characters) +to values. Char tables are specialized for characters, only allowing +particular sorts of ranges to be assigned values. Although this loses +in generality, it makes for extremely fast (constant-time) lookups, and +thus is feasible for applications that do an extremely large number of +lookups (e.g. scanning a buffer for a character in a particular syntax, +where a lookup in the syntax table must occur once per character). + + Note that char tables as a primitive type, and all of the functions +in this section, exist only in XEmacs 20. In XEmacs 19, char tables are +generally implemented using a vector of 256 elements. + + When MULE support exists, the types of ranges that can be assigned +values are + + * all characters + + * an entire charset + + * a single row in a two-octet charset + + * a single character + + When MULE support is not present, the types of ranges that can be +assigned values are + + * all characters + + * a single character + + -- Function: char-table-p object + This function returns non-`nil' if OBJECT is a char table. + +* Menu: + +* Char Table Types:: Char tables have different uses. +* Working With Char Tables:: Creating and working with char tables. + + +File: lispref.info, Node: Char Table Types, Next: Working With Char Tables, Up: Char Tables + +10.13.1 Char Table Types +------------------------ + +Each char table type is used for a different purpose and allows +different sorts of values. The different char table types are + +`category' + Used for category tables, which specify the regexp categories that + a character is in. The valid values are `nil' or a bit vector of + 95 elements. Higher-level Lisp functions are provided for working + with category tables. Currently categories and category tables + only exist when MULE support is present. + +`char' + A generalized char table, for mapping from one character to + another. Used for case tables, syntax matching tables, + `keyboard-translate-table', etc. The valid values are characters. + +`generic' + An even more generalized char table, for mapping from a character + to anything. + +`display' + Used for display tables, which specify how a particular character + is to appear when displayed. #### Not yet implemented. + +`syntax' + Used for syntax tables, which specify the syntax of a particular + character. Higher-level Lisp functions are provided for working + with syntax tables. The valid values are integers. + + -- Function: char-table-type char-table + This function returns the type of char table CHAR-TABLE. + + -- Function: char-table-type-list + This function returns a list of the recognized char table types. + + -- Function: valid-char-table-type-p type + This function returns `t' if TYPE if a recognized char table type. + + +File: lispref.info, Node: Working With Char Tables, Prev: Char Table Types, Up: Char Tables + +10.13.2 Working With Char Tables +-------------------------------- + + -- Function: make-char-table type + This function makes a new, empty char table of type TYPE. TYPE + should be a symbol, one of `char', `category', `display', + `generic', or `syntax'. + + -- Function: put-char-table range value char-table + This function sets the value for chars in RANGE to be VALUE in + CHAR-TABLE. + + RANGE specifies one or more characters to be affected and should be + one of the following: + + * `t' (all characters are affected) + + * A charset (only allowed when MULE support is present) + + * A vector of two elements: a two-octet charset and a row number + (only allowed when MULE support is present) + + * A single character + + VALUE must be a value appropriate for the type of CHAR-TABLE. + + -- Function: get-char-table character char-table + This function finds the value for CHARACTER in CHAR-TABLE. + + -- Function: get-range-char-table range char-table &optional multi + This function finds the value for a range in CHAR-TABLE. If there + is more than one value, MULTI is returned (defaults to `nil'). + + -- Function: reset-char-table char-table + This function resets CHAR-TABLE to its default state. + + -- Function: map-char-table function char-table &optional range + This function maps FUNCTION over entries in CHAR-TABLE, calling it + with two args, each key and value in the table. + + RANGE specifies a subrange to map over and is in the same format + as the RANGE argument to `put-range-table'. If omitted or `t', it + defaults to the entire table. + + -- Function: valid-char-table-value-p value char-table-type + This function returns non-`nil' if VALUE is a valid value for + CHAR-TABLE-TYPE. + + -- Function: check-valid-char-table-value value char-table-type + This function signals an error if VALUE is not a valid value for + CHAR-TABLE-TYPE. + + +File: lispref.info, Node: Lists, Next: Sequences Arrays Vectors, Prev: Strings and Characters, Up: Top + +11 Lists +******** + +A "list" represents a sequence of zero or more elements (which may be +any Lisp objects). The important difference between lists and vectors +is that two or more lists can share part of their structure; in +addition, you can insert or delete elements in a list without copying +the whole list. + +* Menu: + +* Cons Cells:: How lists are made out of cons cells. +* Lists as Boxes:: Graphical notation to explain lists. +* List-related Predicates:: Is this object a list? Comparing two lists. +* List Elements:: Extracting the pieces of a list. +* Building Lists:: Creating list structure. +* Modifying Lists:: Storing new pieces into an existing list. +* Sets And Lists:: A list can represent a finite mathematical set. +* Association Lists:: A list can represent a finite relation or mapping. +* Property Lists:: A different way to represent a finite mapping. +* Weak Lists:: A list with special garbage-collection behavior. + + +File: lispref.info, Node: Cons Cells, Next: Lists as Boxes, Up: Lists + +11.1 Lists and Cons Cells +========================= + +Lists in Lisp are not a primitive data type; they are built up from +"cons cells". A cons cell is a data object that represents an ordered +pair. It records two Lisp objects, one labeled as the CAR, and the +other labeled as the CDR. These names are traditional; see *Note Cons +Cell Type::. CDR is pronounced "could-er." + + A list is a series of cons cells chained together, one cons cell per +element of the list. By convention, the CARs of the cons cells are the +elements of the list, and the CDRs are used to chain the list: the CDR +of each cons cell is the following cons cell. The CDR of the last cons +cell is `nil'. This asymmetry between the CAR and the CDR is entirely +a matter of convention; at the level of cons cells, the CAR and CDR +slots have the same characteristics. + + Because most cons cells are used as part of lists, the phrase "list +structure" has come to mean any structure made out of cons cells. + + The symbol `nil' is considered a list as well as a symbol; it is the +list with no elements. For convenience, the symbol `nil' is considered +to have `nil' as its CDR (and also as its CAR). + + The CDR of any nonempty list L is a list containing all the elements +of L except the first. + + +File: lispref.info, Node: Lists as Boxes, Next: List-related Predicates, Prev: Cons Cells, Up: Lists + +11.2 Lists as Linked Pairs of Boxes +=================================== + +A cons cell can be illustrated as a pair of boxes. The first box +represents the CAR and the second box represents the CDR. Here is an +illustration of the two-element list, `(tulip lily)', made from two +cons cells: + + --------------- --------------- + | car | cdr | | car | cdr | + | tulip | o---------->| lily | nil | + | | | | | | + --------------- --------------- + + Each pair of boxes represents a cons cell. Each box "refers to", +"points to" or "contains" a Lisp object. (These terms are synonymous.) +The first box, which is the CAR of the first cons cell, contains the +symbol `tulip'. The arrow from the CDR of the first cons cell to the +second cons cell indicates that the CDR of the first cons cell points +to the second cons cell. + + The same list can be illustrated in a different sort of box notation +like this: + + ___ ___ ___ ___ + |___|___|--> |___|___|--> nil + | | + | | + --> tulip --> lily + + Here is a more complex illustration, showing the three-element list, +`((pine needles) oak maple)', the first element of which is a +two-element list: + + ___ ___ ___ ___ ___ ___ + |___|___|--> |___|___|--> |___|___|--> nil + | | | + | | | + | --> oak --> maple + | + | ___ ___ ___ ___ + --> |___|___|--> |___|___|--> nil + | | + | | + --> pine --> needles + + The same list represented in the first box notation looks like this: + + -------------- -------------- -------------- + | car | cdr | | car | cdr | | car | cdr | + | o | o------->| oak | o------->| maple | nil | + | | | | | | | | | | + -- | --------- -------------- -------------- + | + | + | -------------- ---------------- + | | car | cdr | | car | cdr | + ------>| pine | o------->| needles | nil | + | | | | | | + -------------- ---------------- + + *Note Cons Cell Type::, for the read and print syntax of cons cells +and lists, and for more "box and arrow" illustrations of lists. + + +File: lispref.info, Node: List-related Predicates, Next: List Elements, Prev: Lists as Boxes, Up: Lists + +11.3 Predicates on Lists +======================== + +The following predicates test whether a Lisp object is an atom, is a +cons cell or is a list, or whether it is the distinguished object +`nil'. (Many of these predicates can be defined in terms of the +others, but they are used so often that it is worth having all of them.) + + -- Function: consp object + This function returns `t' if OBJECT is a cons cell, `nil' + otherwise. `nil' is not a cons cell, although it _is_ a list. + + -- Function: atom object + This function returns `t' if OBJECT is an atom, `nil' otherwise. + All objects except cons cells are atoms. The symbol `nil' is an + atom and is also a list; it is the only Lisp object that is both. + + (atom OBJECT) == (not (consp OBJECT)) + + -- Function: listp object + This function returns `t' if OBJECT is a cons cell or `nil'. + Otherwise, it returns `nil'. + + (listp '(1)) + => t + (listp '()) + => t + + -- Function: nlistp object + This function is the opposite of `listp': it returns `t' if OBJECT + is not a list. Otherwise, it returns `nil'. + + (listp OBJECT) == (not (nlistp OBJECT)) + + -- Function: null object + This function returns `t' if OBJECT is `nil', and returns `nil' + otherwise. This function is identical to `not', but as a matter + of clarity we use `null' when OBJECT is considered a list and + `not' when it is considered a truth value (see `not' in *Note + Combining Conditions::). + + (null '(1)) + => nil + (null '()) + => t + diff -u -r -N xemacs-21.4.18/info/lispref.info-2 xemacs-21.4.19/info/lispref.info-2 --- xemacs-21.4.18/info/lispref.info-2 1969-12-31 19:00:00.000000000 -0500 +++ xemacs-21.4.19/info/lispref.info-2 2006-01-28 18:57:51.000000000 -0500 @@ -0,0 +1,7484 @@ +This is ../info/lispref.info, produced by makeinfo version 4.8 from +lispref/lispref.texi. + +INFO-DIR-SECTION XEmacs Editor +START-INFO-DIR-ENTRY +* Lispref: (lispref). XEmacs Lisp Reference Manual. +END-INFO-DIR-ENTRY + + Edition History: + + GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU +Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid +Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994 +XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995 +GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp +Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp +Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp +Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May, +November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998 + + Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software +Foundation, Inc. Copyright (C) 1994, 1995 Sun Microsystems, Inc. +Copyright (C) 1995, 1996 Ben Wing. + + Permission is granted to make and distribute verbatim copies of this +manual provided the copyright notice and this permission notice are +preserved on all copies. + + Permission is granted to copy and distribute modified versions of +this manual under the conditions for verbatim copying, provided that the +entire resulting derived work is distributed under the terms of a +permission notice identical to this one. + + Permission is granted to copy and distribute translations of this +manual into another language, under the above conditions for modified +versions, except that this permission notice may be stated in a +translation approved by the Foundation. + + Permission is granted to copy and distribute modified versions of +this manual under the conditions for verbatim copying, provided also +that the section entitled "GNU General Public License" is included +exactly as in the original, and provided that the entire resulting +derived work is distributed under the terms of a permission notice +identical to this one. + + Permission is granted to copy and distribute translations of this +manual into another language, under the above conditions for modified +versions, except that the section entitled "GNU General Public License" +may be included in a translation approved by the Free Software +Foundation instead of in the original English. + + +File: lispref.info, Node: List Elements, Next: Building Lists, Prev: List-related Predicates, Up: Lists + +11.4 Accessing Elements of Lists +================================ + + -- Function: car cons-cell + This function returns the value pointed to by the first pointer of + the cons cell CONS-CELL. Expressed another way, this function + returns the CAR of CONS-CELL. + + As a special case, if CONS-CELL is `nil', then `car' is defined to + return `nil'; therefore, any list is a valid argument for `car'. + An error is signaled if the argument is not a cons cell or `nil'. + + (car '(a b c)) + => a + (car '()) + => nil + + -- Function: cdr cons-cell + This function returns the value pointed to by the second pointer of + the cons cell CONS-CELL. Expressed another way, this function + returns the CDR of CONS-CELL. + + As a special case, if CONS-CELL is `nil', then `cdr' is defined to + return `nil'; therefore, any list is a valid argument for `cdr'. + An error is signaled if the argument is not a cons cell or `nil'. + + (cdr '(a b c)) + => (b c) + (cdr '()) + => nil + + -- Function: car-safe object + This function lets you take the CAR of a cons cell while avoiding + errors for other data types. It returns the CAR of OBJECT if + OBJECT is a cons cell, `nil' otherwise. This is in contrast to + `car', which signals an error if OBJECT is not a list. + + (car-safe OBJECT) + == + (let ((x OBJECT)) + (if (consp x) + (car x) + nil)) + + -- Function: cdr-safe object + This function lets you take the CDR of a cons cell while avoiding + errors for other data types. It returns the CDR of OBJECT if + OBJECT is a cons cell, `nil' otherwise. This is in contrast to + `cdr', which signals an error if OBJECT is not a list. + + (cdr-safe OBJECT) + == + (let ((x OBJECT)) + (if (consp x) + (cdr x) + nil)) + + -- Function: nth n list + This function returns the Nth element of LIST. Elements are + numbered starting with zero, so the CAR of LIST is element number + zero. If the length of LIST is N or less, the value is `nil'. + + If N is negative, `nth' returns the first element of LIST. + + (nth 2 '(1 2 3 4)) + => 3 + (nth 10 '(1 2 3 4)) + => nil + (nth -3 '(1 2 3 4)) + => 1 + + (nth n x) == (car (nthcdr n x)) + + -- Function: nthcdr n list + This function returns the Nth CDR of LIST. In other words, it + removes the first N links of LIST and returns what follows. + + If N is zero or negative, `nthcdr' returns all of LIST. If the + length of LIST is N or less, `nthcdr' returns `nil'. + + (nthcdr 1 '(1 2 3 4)) + => (2 3 4) + (nthcdr 10 '(1 2 3 4)) + => nil + (nthcdr -3 '(1 2 3 4)) + => (1 2 3 4) + +Many convenience functions are provided to make it easier for you to +access particular elements in a nested list. All of these can be +rewritten in terms of the functions just described. + + -- Function: caar cons-cell + -- Function: cadr cons-cell + -- Function: cdar cons-cell + -- Function: cddr cons-cell + -- Function: caaar cons-cell + -- Function: caadr cons-cell + -- Function: cadar cons-cell + -- Function: caddr cons-cell + -- Function: cdaar cons-cell + -- Function: cdadr cons-cell + -- Function: cddar cons-cell + -- Function: cdddr cons-cell + -- Function: caaaar cons-cell + -- Function: caaadr cons-cell + -- Function: caadar cons-cell + -- Function: caaddr cons-cell + -- Function: cadaar cons-cell + -- Function: cadadr cons-cell + -- Function: caddar cons-cell + -- Function: cadddr cons-cell + -- Function: cdaaar cons-cell + -- Function: cdaadr cons-cell + -- Function: cdadar cons-cell + -- Function: cdaddr cons-cell + -- Function: cddaar cons-cell + -- Function: cddadr cons-cell + -- Function: cdddar cons-cell + -- Function: cddddr cons-cell + Each of these functions is equivalent to one or more applications + of `car' and/or `cdr'. For example, + + (cadr x) + + is equivalent to + + (car (cdr x)) + + and + + (cdaddr x) + + is equivalent to + + (cdr (car (cdr (cdr x)))) + + That is to say, read the a's and d's from right to left and apply + a `car' or `cdr' for each a or d found, respectively. + + -- Function: first list + This is equivalent to `(nth 0 LIST)', i.e. the first element of + LIST. (Note that this is also equivalent to `car'.) + + -- Function: second list + This is equivalent to `(nth 1 LIST)', i.e. the second element of + LIST. + + -- Function: third list + -- Function: fourth list + -- Function: fifth list + -- Function: sixth list + -- Function: seventh list + -- Function: eighth list + -- Function: ninth list + -- Function: tenth list + These are equivalent to `(nth 2 LIST)' through `(nth 9 LIST)' + respectively, i.e. the third through tenth elements of LIST. + + +File: lispref.info, Node: Building Lists, Next: Modifying Lists, Prev: List Elements, Up: Lists + +11.5 Building Cons Cells and Lists +================================== + +Many functions build lists, as lists reside at the very heart of Lisp. +`cons' is the fundamental list-building function; however, it is +interesting to note that `list' is used more times in the source code +for Emacs than `cons'. + + -- Function: cons object1 object2 + This function is the fundamental function used to build new list + structure. It creates a new cons cell, making OBJECT1 the CAR, + and OBJECT2 the CDR. It then returns the new cons cell. The + arguments OBJECT1 and OBJECT2 may be any Lisp objects, but most + often OBJECT2 is a list. + + (cons 1 '(2)) + => (1 2) + (cons 1 '()) + => (1) + (cons 1 2) + => (1 . 2) + + `cons' is often used to add a single element to the front of a + list. This is called "consing the element onto the list". For + example: + + (setq list (cons newelt list)) + + Note that there is no conflict between the variable named `list' + used in this example and the function named `list' described below; + any symbol can serve both purposes. + + -- Function: list &rest objects + This function creates a list with OBJECTS as its elements. The + resulting list is always `nil'-terminated. If no OBJECTS are + given, the empty list is returned. + + (list 1 2 3 4 5) + => (1 2 3 4 5) + (list 1 2 '(3 4 5) 'foo) + => (1 2 (3 4 5) foo) + (list) + => nil + + -- Function: make-list length object + This function creates a list of length LENGTH, in which all the + elements have the identical value OBJECT. Compare `make-list' + with `make-string' (*note Creating Strings::). + + (make-list 3 'pigs) + => (pigs pigs pigs) + (make-list 0 'pigs) + => nil + + -- Function: append &rest sequences + This function returns a list containing all the elements of + SEQUENCES. The SEQUENCES may be lists, vectors, or strings, but + the last one should be a list. All arguments except the last one + are copied, so none of them are altered. + + More generally, the final argument to `append' may be any Lisp + object. The final argument is not copied or converted; it becomes + the CDR of the last cons cell in the new list. If the final + argument is itself a list, then its elements become in effect + elements of the result list. If the final element is not a list, + the result is a "dotted list" since its final CDR is not `nil' as + required in a true list. + + See `nconc' in *Note Rearrangement::, for a way to join lists with + no copying. + + Here is an example of using `append': + + (setq trees '(pine oak)) + => (pine oak) + (setq more-trees (append '(maple birch) trees)) + => (maple birch pine oak) + + trees + => (pine oak) + more-trees + => (maple birch pine oak) + (eq trees (cdr (cdr more-trees))) + => t + + You can see how `append' works by looking at a box diagram. The + variable `trees' is set to the list `(pine oak)' and then the + variable `more-trees' is set to the list `(maple birch pine oak)'. + However, the variable `trees' continues to refer to the original + list: + + more-trees trees + | | + | ___ ___ ___ ___ -> ___ ___ ___ ___ + --> |___|___|--> |___|___|--> |___|___|--> |___|___|--> nil + | | | | + | | | | + --> maple -->birch --> pine --> oak + + An empty sequence contributes nothing to the value returned by + `append'. As a consequence of this, a final `nil' argument forces + a copy of the previous argument. + + trees + => (pine oak) + (setq wood (append trees ())) + => (pine oak) + wood + => (pine oak) + (eq wood trees) + => nil + + This once was the usual way to copy a list, before the function + `copy-sequence' was invented. *Note Sequences Arrays Vectors::. + + With the help of `apply', we can append all the lists in a list of + lists: + + (apply 'append '((a b c) nil (x y z) nil)) + => (a b c x y z) + + If no SEQUENCES are given, `nil' is returned: + + (append) + => nil + + Here are some examples where the final argument is not a list: + + (append '(x y) 'z) + => (x y . z) + (append '(x y) [z]) + => (x y . [z]) + + The second example shows that when the final argument is a + sequence but not a list, the sequence's elements do not become + elements of the resulting list. Instead, the sequence becomes the + final CDR, like any other non-list final argument. + + The `append' function also allows integers as arguments. It + converts them to strings of digits, making up the decimal print + representation of the integer, and then uses the strings instead + of the original integers. *Don't use this feature; we plan to + eliminate it. If you already use this feature, change your + programs now!* The proper way to convert an integer to a decimal + number in this way is with `format' (*note Formatting Strings::) + or `number-to-string' (*note String Conversion::). + + -- Function: reverse list + This function creates a new list whose elements are the elements of + LIST, but in reverse order. The original argument LIST is _not_ + altered. + + (setq x '(1 2 3 4)) + => (1 2 3 4) + (reverse x) + => (4 3 2 1) + x + => (1 2 3 4) + + +File: lispref.info, Node: Modifying Lists, Next: Sets And Lists, Prev: Building Lists, Up: Lists + +11.6 Modifying Existing List Structure +====================================== + +You can modify the CAR and CDR contents of a cons cell with the +primitives `setcar' and `setcdr'. + + Common Lisp note: Common Lisp uses functions `rplaca' and `rplacd' + to alter list structure; they change structure the same way as + `setcar' and `setcdr', but the Common Lisp functions return the + cons cell while `setcar' and `setcdr' return the new CAR or CDR. + +* Menu: + +* Setcar:: Replacing an element in a list. +* Setcdr:: Replacing part of the list backbone. + This can be used to remove or add elements. +* Rearrangement:: Reordering the elements in a list; combining lists. + + +File: lispref.info, Node: Setcar, Next: Setcdr, Up: Modifying Lists + +11.6.1 Altering List Elements with `setcar' +------------------------------------------- + +Changing the CAR of a cons cell is done with `setcar'. When used on a +list, `setcar' replaces one element of a list with a different element. + + -- Function: setcar cons-cell object + This function stores OBJECT as the new CAR of CONS-CELL, replacing + its previous CAR. It returns the value OBJECT. For example: + + (setq x '(1 2)) + => (1 2) + (setcar x 4) + => 4 + x + => (4 2) + + When a cons cell is part of the shared structure of several lists, +storing a new CAR into the cons changes one element of each of these +lists. Here is an example: + + ;; Create two lists that are partly shared. + (setq x1 '(a b c)) + => (a b c) + (setq x2 (cons 'z (cdr x1))) + => (z b c) + + ;; Replace the CAR of a shared link. + (setcar (cdr x1) 'foo) + => foo + x1 ; Both lists are changed. + => (a foo c) + x2 + => (z foo c) + + ;; Replace the CAR of a link that is not shared. + (setcar x1 'baz) + => baz + x1 ; Only one list is changed. + => (baz foo c) + x2 + => (z foo c) + + Here is a graphical depiction of the shared structure of the two +lists in the variables `x1' and `x2', showing why replacing `b' changes +them both: + + ___ ___ ___ ___ ___ ___ + x1---> |___|___|----> |___|___|--> |___|___|--> nil + | --> | | + | | | | + --> a | --> b --> c + | + ___ ___ | + x2--> |___|___|-- + | + | + --> z + + Here is an alternative form of box diagram, showing the same +relationship: + + x1: + -------------- -------------- -------------- + | car | cdr | | car | cdr | | car | cdr | + | a | o------->| b | o------->| c | nil | + | | | -->| | | | | | + -------------- | -------------- -------------- + | + x2: | + -------------- | + | car | cdr | | + | z | o---- + | | | + -------------- + + +File: lispref.info, Node: Setcdr, Next: Rearrangement, Prev: Setcar, Up: Modifying Lists + +11.6.2 Altering the CDR of a List +--------------------------------- + +The lowest-level primitive for modifying a CDR is `setcdr': + + -- Function: setcdr cons-cell object + This function stores OBJECT as the new CDR of CONS-CELL, replacing + its previous CDR. It returns the value OBJECT. + + Here is an example of replacing the CDR of a list with a different +list. All but the first element of the list are removed in favor of a +different sequence of elements. The first element is unchanged, +because it resides in the CAR of the list, and is not reached via the +CDR. + + (setq x '(1 2 3)) + => (1 2 3) + (setcdr x '(4)) + => (4) + x + => (1 4) + + You can delete elements from the middle of a list by altering the +CDRs of the cons cells in the list. For example, here we delete the +second element, `b', from the list `(a b c)', by changing the CDR of +the first cell: + + (setq x1 '(a b c)) + => (a b c) + (setcdr x1 (cdr (cdr x1))) + => (c) + x1 + => (a c) + + Here is the result in box notation: + + -------------------- + | | + -------------- | -------------- | -------------- + | car | cdr | | | car | cdr | -->| car | cdr | + | a | o----- | b | o-------->| c | nil | + | | | | | | | | | + -------------- -------------- -------------- + +The second cons cell, which previously held the element `b', still +exists and its CAR is still `b', but it no longer forms part of this +list. + + It is equally easy to insert a new element by changing CDRs: + + (setq x1 '(a b c)) + => (a b c) + (setcdr x1 (cons 'd (cdr x1))) + => (d b c) + x1 + => (a d b c) + + Here is this result in box notation: + + -------------- ------------- ------------- + | car | cdr | | car | cdr | | car | cdr | + | a | o | -->| b | o------->| c | nil | + | | | | | | | | | | | + --------- | -- | ------------- ------------- + | | + ----- -------- + | | + | --------------- | + | | car | cdr | | + -->| d | o------ + | | | + --------------- + + +File: lispref.info, Node: Rearrangement, Prev: Setcdr, Up: Modifying Lists + +11.6.3 Functions that Rearrange Lists +------------------------------------- + +Here are some functions that rearrange lists "destructively" by +modifying the CDRs of their component cons cells. We call these +functions "destructive" because they chew up the original lists passed +to them as arguments, to produce a new list that is the returned value. + + See `delq', in *Note Sets And Lists::, for another function that +modifies cons cells. + + -- Function: nconc &rest lists + This function returns a list containing all the elements of LISTS. + Unlike `append' (*note Building Lists::), the LISTS are _not_ + copied. Instead, the last CDR of each of the LISTS is changed to + refer to the following list. The last of the LISTS is not + altered. For example: + + (setq x '(1 2 3)) + => (1 2 3) + (nconc x '(4 5)) + => (1 2 3 4 5) + x + => (1 2 3 4 5) + + Since the last argument of `nconc' is not itself modified, it is + reasonable to use a constant list, such as `'(4 5)', as in the + above example. For the same reason, the last argument need not be + a list: + + (setq x '(1 2 3)) + => (1 2 3) + (nconc x 'z) + => (1 2 3 . z) + x + => (1 2 3 . z) + + A common pitfall is to use a quoted constant list as a non-last + argument to `nconc'. If you do this, your program will change + each time you run it! Here is what happens: + + (defun add-foo (x) ; We want this function to add + (nconc '(foo) x)) ; `foo' to the front of its arg. + + (symbol-function 'add-foo) + => (lambda (x) (nconc (quote (foo)) x)) + + (setq xx (add-foo '(1 2))) ; It seems to work. + => (foo 1 2) + (setq xy (add-foo '(3 4))) ; What happened? + => (foo 1 2 3 4) + (eq xx xy) + => t + + (symbol-function 'add-foo) + => (lambda (x) (nconc (quote (foo 1 2 3 4) x))) + + -- Function: nreverse list + This function reverses the order of the elements of LIST. Unlike + `reverse', `nreverse' alters its argument by reversing the CDRs in + the cons cells forming the list. The cons cell that used to be + the last one in LIST becomes the first cell of the value. + + For example: + + (setq x '(1 2 3 4)) + => (1 2 3 4) + x + => (1 2 3 4) + (nreverse x) + => (4 3 2 1) + ;; The cell that was first is now last. + x + => (1) + + To avoid confusion, we usually store the result of `nreverse' back + in the same variable which held the original list: + + (setq x (nreverse x)) + + Here is the `nreverse' of our favorite example, `(a b c)', + presented graphically: + + Original list head: Reversed list: + ------------- ------------- ------------ + | car | cdr | | car | cdr | | car | cdr | + | a | nil |<-- | b | o |<-- | c | o | + | | | | | | | | | | | | | + ------------- | --------- | - | -------- | - + | | | | + ------------- ------------ + + -- Function: sort list predicate + This function sorts LIST stably, though destructively, and returns + the sorted list. It compares elements using PREDICATE. A stable + sort is one in which elements with equal sort keys maintain their + relative order before and after the sort. Stability is important + when successive sorts are used to order elements according to + different criteria. + + The argument PREDICATE must be a function that accepts two + arguments. It is called with two elements of LIST. To get an + increasing order sort, the PREDICATE should return `t' if the + first element is "less than" the second, or `nil' if not. + + The destructive aspect of `sort' is that it rearranges the cons + cells forming LIST by changing CDRs. A nondestructive sort + function would create new cons cells to store the elements in their + sorted order. If you wish to make a sorted copy without + destroying the original, copy it first with `copy-sequence' and + then sort. + + Sorting does not change the CARs of the cons cells in LIST; the + cons cell that originally contained the element `a' in LIST still + has `a' in its CAR after sorting, but it now appears in a + different position in the list due to the change of CDRs. For + example: + + (setq nums '(1 3 2 6 5 4 0)) + => (1 3 2 6 5 4 0) + (sort nums '<) + => (0 1 2 3 4 5 6) + nums + => (1 2 3 4 5 6) + + Note that the list in `nums' no longer contains 0; this is the same + cons cell that it was before, but it is no longer the first one in + the list. Don't assume a variable that formerly held the argument + now holds the entire sorted list! Instead, save the result of + `sort' and use that. Most often we store the result back into the + variable that held the original list: + + (setq nums (sort nums '<)) + + *Note Sorting::, for more functions that perform sorting. See + `documentation' in *Note Accessing Documentation::, for a useful + example of `sort'. + + +File: lispref.info, Node: Sets And Lists, Next: Association Lists, Prev: Modifying Lists, Up: Lists + +11.7 Using Lists as Sets +======================== + +A list can represent an unordered mathematical set--simply consider a +value an element of a set if it appears in the list, and ignore the +order of the list. To form the union of two sets, use `append' (as +long as you don't mind having duplicate elements). Other useful +functions for sets include `memq' and `delq', and their `equal' +versions, `member' and `delete'. + + Common Lisp note: Common Lisp has functions `union' (which avoids + duplicate elements) and `intersection' for set operations, but + XEmacs Lisp does not have them. You can write them in Lisp if you + wish. + + -- Function: memq object list + This function tests to see whether OBJECT is a member of LIST. If + it is, `memq' returns a list starting with the first occurrence of + OBJECT. Otherwise, it returns `nil'. The letter `q' in `memq' + says that it uses `eq' to compare OBJECT against the elements of + the list. For example: + + (memq 'b '(a b c b a)) + => (b c b a) + (memq '(2) '((1) (2))) ; `(2)' and `(2)' are not `eq'. + => nil + + -- Function: delq object list + This function destructively removes all elements `eq' to OBJECT + from LIST. The letter `q' in `delq' says that it uses `eq' to + compare OBJECT against the elements of the list, like `memq'. + + When `delq' deletes elements from the front of the list, it does so +simply by advancing down the list and returning a sublist that starts +after those elements: + + (delq 'a '(a b c)) == (cdr '(a b c)) + + When an element to be deleted appears in the middle of the list, +removing it involves changing the CDRs (*note Setcdr::). + + (setq sample-list '(a b c (4))) + => (a b c (4)) + (delq 'a sample-list) + => (b c (4)) + sample-list + => (a b c (4)) + (delq 'c sample-list) + => (a b (4)) + sample-list + => (a b (4)) + + Note that `(delq 'c sample-list)' modifies `sample-list' to splice +out the third element, but `(delq 'a sample-list)' does not splice +anything--it just returns a shorter list. Don't assume that a variable +which formerly held the argument LIST now has fewer elements, or that +it still holds the original list! Instead, save the result of `delq' +and use that. Most often we store the result back into the variable +that held the original list: + + (setq flowers (delq 'rose flowers)) + + In the following example, the `(4)' that `delq' attempts to match +and the `(4)' in the `sample-list' are not `eq': + + (delq '(4) sample-list) + => (a c (4)) + + The following two functions are like `memq' and `delq' but use +`equal' rather than `eq' to compare elements. They are new in Emacs 19. + + -- Function: member object list + The function `member' tests to see whether OBJECT is a member of + LIST, comparing members with OBJECT using `equal'. If OBJECT is a + member, `member' returns a list starting with its first occurrence + in LIST. Otherwise, it returns `nil'. + + Compare this with `memq': + + (member '(2) '((1) (2))) ; `(2)' and `(2)' are `equal'. + => ((2)) + (memq '(2) '((1) (2))) ; `(2)' and `(2)' are not `eq'. + => nil + ;; Two strings with the same contents are `equal'. + (member "foo" '("foo" "bar")) + => ("foo" "bar") + + -- Function: delete object list + This function destructively removes all elements `equal' to OBJECT + from LIST. It is to `delq' as `member' is to `memq': it uses + `equal' to compare elements with OBJECT, like `member'; when it + finds an element that matches, it removes the element just as + `delq' would. For example: + + (delete '(2) '((2) (1) (2))) + => '((1)) + + Common Lisp note: The functions `member' and `delete' in XEmacs + Lisp are derived from Maclisp, not Common Lisp. The Common Lisp + versions do not use `equal' to compare elements. + + See also the function `add-to-list', in *Note Setting Variables::, +for another way to add an element to a list stored in a variable. + + +File: lispref.info, Node: Association Lists, Next: Property Lists, Prev: Sets And Lists, Up: Lists + +11.8 Association Lists +====================== + +An "association list", or "alist" for short, records a mapping from +keys to values. It is a list of cons cells called "associations": the +CAR of each cell is the "key", and the CDR is the "associated value".(1) + + Here is an example of an alist. The key `pine' is associated with +the value `cones'; the key `oak' is associated with `acorns'; and the +key `maple' is associated with `seeds'. + + '((pine . cones) + (oak . acorns) + (maple . seeds)) + + The associated values in an alist may be any Lisp objects; so may the +keys. For example, in the following alist, the symbol `a' is +associated with the number `1', and the string `"b"' is associated with +the _list_ `(2 3)', which is the CDR of the alist element: + + ((a . 1) ("b" 2 3)) + + Sometimes it is better to design an alist to store the associated +value in the CAR of the CDR of the element. Here is an example: + + '((rose red) (lily white) (buttercup yellow)) + +Here we regard `red' as the value associated with `rose'. One +advantage of this method is that you can store other related +information--even a list of other items--in the CDR of the CDR. One +disadvantage is that you cannot use `rassq' (see below) to find the +element containing a given value. When neither of these considerations +is important, the choice is a matter of taste, as long as you are +consistent about it for any given alist. + + Note that the same alist shown above could be regarded as having the +associated value in the CDR of the element; the value associated with +`rose' would be the list `(red)'. + + Association lists are often used to record information that you might +otherwise keep on a stack, since new associations may be added easily to +the front of the list. When searching an association list for an +association with a given key, the first one found is returned, if there +is more than one. + + In XEmacs Lisp, it is _not_ an error if an element of an association +list is not a cons cell. The alist search functions simply ignore such +elements. Many other versions of Lisp signal errors in such cases. + + Note that property lists are similar to association lists in several +respects. A property list behaves like an association list in which +each key can occur only once. *Note Property Lists::, for a comparison +of property lists and association lists. + + -- Function: assoc key alist + This function returns the first association for KEY in ALIST. It + compares KEY against the alist elements using `equal' (*note + Equality Predicates::). It returns `nil' if no association in + ALIST has a CAR `equal' to KEY. For example: + + (setq trees '((pine . cones) (oak . acorns) (maple . seeds))) + => ((pine . cones) (oak . acorns) (maple . seeds)) + (assoc 'oak trees) + => (oak . acorns) + (cdr (assoc 'oak trees)) + => acorns + (assoc 'birch trees) + => nil + + Here is another example, in which the keys and values are not + symbols: + + (setq needles-per-cluster + '((2 "Austrian Pine" "Red Pine") + (3 "Pitch Pine") + (5 "White Pine"))) + + (cdr (assoc 3 needles-per-cluster)) + => ("Pitch Pine") + (cdr (assoc 2 needles-per-cluster)) + => ("Austrian Pine" "Red Pine") + + -- Function: rassoc value alist + This function returns the first association with value VALUE in + ALIST. It returns `nil' if no association in ALIST has a CDR + `equal' to VALUE. + + `rassoc' is like `assoc' except that it compares the CDR of each + ALIST association instead of the CAR. You can think of this as + "reverse `assoc'", finding the key for a given value. + + -- Function: assq key alist + This function is like `assoc' in that it returns the first + association for KEY in ALIST, but it makes the comparison using + `eq' instead of `equal'. `assq' returns `nil' if no association + in ALIST has a CAR `eq' to KEY. This function is used more often + than `assoc', since `eq' is faster than `equal' and most alists + use symbols as keys. *Note Equality Predicates::. + + (setq trees '((pine . cones) (oak . acorns) (maple . seeds))) + => ((pine . cones) (oak . acorns) (maple . seeds)) + (assq 'pine trees) + => (pine . cones) + + On the other hand, `assq' is not usually useful in alists where the + keys may not be symbols: + + (setq leaves + '(("simple leaves" . oak) + ("compound leaves" . horsechestnut))) + + (assq "simple leaves" leaves) + => nil + (assoc "simple leaves" leaves) + => ("simple leaves" . oak) + + -- Function: rassq value alist + This function returns the first association with value VALUE in + ALIST. It returns `nil' if no association in ALIST has a CDR `eq' + to VALUE. + + `rassq' is like `assq' except that it compares the CDR of each + ALIST association instead of the CAR. You can think of this as + "reverse `assq'", finding the key for a given value. + + For example: + + (setq trees '((pine . cones) (oak . acorns) (maple . seeds))) + + (rassq 'acorns trees) + => (oak . acorns) + (rassq 'spores trees) + => nil + + Note that `rassq' cannot search for a value stored in the CAR of + the CDR of an element: + + (setq colors '((rose red) (lily white) (buttercup yellow))) + + (rassq 'white colors) + => nil + + In this case, the CDR of the association `(lily white)' is not the + symbol `white', but rather the list `(white)'. This becomes + clearer if the association is written in dotted pair notation: + + (lily white) == (lily . (white)) + + -- Function: remassoc key alist + This function deletes by side effect any associations with key KEY + in ALIST--i.e. it removes any elements from ALIST whose `car' is + `equal' to KEY. The modified ALIST is returned. + + If the first member of ALIST has a `car' that is `equal' to KEY, + there is no way to remove it by side effect; therefore, write + `(setq foo (remassoc key foo))' to be sure of changing the value + of `foo'. + + -- Function: remassq key alist + This function deletes by side effect any associations with key KEY + in ALIST--i.e. it removes any elements from ALIST whose `car' is + `eq' to KEY. The modified ALIST is returned. + + This function is exactly like `remassoc', but comparisons between + KEY and keys in ALIST are done using `eq' instead of `equal'. + + -- Function: remrassoc value alist + This function deletes by side effect any associations with value + VALUE in ALIST--i.e. it removes any elements from ALIST whose + `cdr' is `equal' to VALUE. The modified ALIST is returned. + + If the first member of ALIST has a `car' that is `equal' to VALUE, + there is no way to remove it by side effect; therefore, write + `(setq foo (remassoc value foo))' to be sure of changing the value + of `foo'. + + `remrassoc' is like `remassoc' except that it compares the CDR of + each ALIST association instead of the CAR. You can think of this + as "reverse `remassoc'", removing an association based on its + value instead of its key. + + -- Function: remrassq value alist + This function deletes by side effect any associations with value + VALUE in ALIST--i.e. it removes any elements from ALIST whose + `cdr' is `eq' to VALUE. The modified ALIST is returned. + + This function is exactly like `remrassoc', but comparisons between + VALUE and values in ALIST are done using `eq' instead of `equal'. + + -- Function: copy-alist alist + This function returns a two-level deep copy of ALIST: it creates a + new copy of each association, so that you can alter the + associations of the new alist without changing the old one. + + (setq needles-per-cluster + '((2 . ("Austrian Pine" "Red Pine")) + (3 . ("Pitch Pine")) + (5 . ("White Pine")))) + => + ((2 "Austrian Pine" "Red Pine") + (3 "Pitch Pine") + (5 "White Pine")) + + (setq copy (copy-alist needles-per-cluster)) + => + ((2 "Austrian Pine" "Red Pine") + (3 "Pitch Pine") + (5 "White Pine")) + + (eq needles-per-cluster copy) + => nil + (equal needles-per-cluster copy) + => t + (eq (car needles-per-cluster) (car copy)) + => nil + (cdr (car (cdr needles-per-cluster))) + => ("Pitch Pine") + (eq (cdr (car (cdr needles-per-cluster))) + (cdr (car (cdr copy)))) + => t + + This example shows how `copy-alist' makes it possible to change + the associations of one copy without affecting the other: + + (setcdr (assq 3 copy) '("Martian Vacuum Pine")) + (cdr (assq 3 needles-per-cluster)) + => ("Pitch Pine") + + ---------- Footnotes ---------- + + (1) This usage of "key" is not related to the term "key sequence"; +it means a value used to look up an item in a table. In this case, the +table is the alist, and the alist associations are the items. + + +File: lispref.info, Node: Property Lists, Next: Weak Lists, Prev: Association Lists, Up: Lists + +11.9 Property Lists +=================== + +A "property list" (or "plist") is another way of representing a mapping +from keys to values. Instead of the list consisting of conses of a key +and a value, the keys and values alternate as successive entries in the +list. Thus, the association list + + ((a . 1) (b . 2) (c . 3)) + + has the equivalent property list form + + (a 1 b 2 c 3) + + Property lists are used to represent the properties associated with +various sorts of objects, such as symbols, strings, frames, etc. The +convention is that property lists can be modified in-place, while +association lists generally are not. + + Plists come in two varieties: "normal" plists, whose keys are +compared with `eq', and "lax" plists, whose keys are compared with +`equal', + + -- Function: valid-plist-p plist + Given a plist, this function returns non-`nil' if its format is + correct. If it returns `nil', `check-valid-plist' will signal an + error when given the plist; that means it's a malformed or circular + plist or has non-symbols as keywords. + + -- Function: check-valid-plist plist + Given a plist, this function signals an error if there is anything + wrong with it. This means that it's a malformed or circular plist. + +* Menu: + +* Working With Normal Plists:: Functions for normal plists. +* Working With Lax Plists:: Functions for lax plists. +* Converting Plists To/From Alists:: Alist to plist and vice-versa. + + +File: lispref.info, Node: Working With Normal Plists, Next: Working With Lax Plists, Up: Property Lists + +11.9.1 Working With Normal Plists +--------------------------------- + + -- Function: plist-get plist property &optional default + This function extracts a value from a property list. The function + returns the value corresponding to the given PROPERTY, or DEFAULT + if PROPERTY is not one of the properties on the list. + + -- Function: plist-put plist property value + This function changes the value in PLIST of PROPERTY to VALUE. If + PROPERTY is already a property on the list, its value is set to + VALUE, otherwise the new PROPERTY VALUE pair is added. The new + plist is returned; use `(setq x (plist-put x property value))' to + be sure to use the new value. The PLIST is modified by side + effects. + + -- Function: plist-remprop plist property + This function removes from PLIST the property PROPERTY and its + value. The new plist is returned; use `(setq x (plist-remprop x + property))' to be sure to use the new value. The PLIST is + modified by side effects. + + -- Function: plist-member plist property + This function returns `t' if PROPERTY has a value specified in + PLIST. + + In the following functions, if optional arg NIL-MEANS-NOT-PRESENT is +non-`nil', then a property with a `nil' value is ignored or removed. +This feature is a virus that has infected old Lisp implementations (and +thus E-Lisp, due to RMS's enamorment with old Lisps), but should not be +used except for backward compatibility. + + -- Function: plists-eq a b &optional nil-means-not-present + This function returns non-`nil' if property lists A and B are `eq' + (i.e. their values are `eq'). + + -- Function: plists-equal a b &optional nil-means-not-present + This function returns non-`nil' if property lists A and B are + `equal' (i.e. their values are `equal'; their keys are still + compared using `eq'). + + -- Function: canonicalize-plist plist &optional nil-means-not-present + This function destructively removes any duplicate entries from a + plist. In such cases, the first entry applies. + + The new plist is returned. If NIL-MEANS-NOT-PRESENT is given, the + return value may not be `eq' to the passed-in value, so make sure + to `setq' the value back into where it came from. + + +File: lispref.info, Node: Working With Lax Plists, Next: Converting Plists To/From Alists, Prev: Working With Normal Plists, Up: Property Lists + +11.9.2 Working With Lax Plists +------------------------------ + +Recall that a "lax plist" is a property list whose keys are compared +using `equal' instead of `eq'. + + -- Function: lax-plist-get lax-plist property &optional default + This function extracts a value from a lax property list. The + function returns the value corresponding to the given PROPERTY, or + DEFAULT if PROPERTY is not one of the properties on the list. + + -- Function: lax-plist-put lax-plist property value + This function changes the value in LAX-PLIST of PROPERTY to VALUE. + + -- Function: lax-plist-remprop lax-plist property + This function removes from LAX-PLIST the property PROPERTY and its + value. The new plist is returned; use `(setq x (lax-plist-remprop + x property))' to be sure to use the new value. The LAX-PLIST is + modified by side effects. + + -- Function: lax-plist-member lax-plist property + This function returns `t' if PROPERTY has a value specified in + LAX-PLIST. + + In the following functions, if optional arg NIL-MEANS-NOT-PRESENT is +non-`nil', then a property with a `nil' value is ignored or removed. +This feature is a virus that has infected old Lisp implementations (and +thus E-Lisp, due to RMS's enamorment with old Lisps), but should not be +used except for backward compatibility. + + -- Function: lax-plists-eq a b &optional nil-means-not-present + This function returns non-`nil' if lax property lists A and B are + `eq' (i.e. their values are `eq'; their keys are still compared + using `equal'). + + -- Function: lax-plists-equal a b &optional nil-means-not-present + This function returns non-`nil' if lax property lists A and B are + `equal' (i.e. their values are `equal'). + + -- Function: canonicalize-lax-plist lax-plist &optional + nil-means-not-present + This function destructively removes any duplicate entries from a + lax plist. In such cases, the first entry applies. + + The new plist is returned. If NIL-MEANS-NOT-PRESENT is given, the + return value may not be `eq' to the passed-in value, so make sure + to `setq' the value back into where it came from. + + +File: lispref.info, Node: Converting Plists To/From Alists, Prev: Working With Lax Plists, Up: Property Lists + +11.9.3 Converting Plists To/From Alists +--------------------------------------- + + -- Function: alist-to-plist alist + This function converts association list ALIST into the equivalent + property-list form. The plist is returned. This converts from + + ((a . 1) (b . 2) (c . 3)) + + into + + (a 1 b 2 c 3) + + The original alist is not modified. + + -- Function: plist-to-alist plist + This function converts property list PLIST into the equivalent + association-list form. The alist is returned. This converts from + + (a 1 b 2 c 3) + + into + + ((a . 1) (b . 2) (c . 3)) + + The original plist is not modified. + + The following two functions are equivalent to the preceding two +except that they destructively modify their arguments, using cons cells +from the original list to form the new list rather than allocating new +cons cells. + + -- Function: destructive-alist-to-plist alist + This function destructively converts association list ALIST into + the equivalent property-list form. The plist is returned. + + -- Function: destructive-plist-to-alist plist + This function destructively converts property list PLIST into the + equivalent association-list form. The alist is returned. + + +File: lispref.info, Node: Weak Lists, Prev: Property Lists, Up: Lists + +11.10 Weak Lists +================ + +A "weak list" is a special sort of list whose members are not counted +as references for the purpose of garbage collection. This means that, +for any object in the list, if there are no references to the object +anywhere outside of the list (or other weak list or weak hash table), +that object will disappear the next time a garbage collection happens. +Weak lists can be useful for keeping track of things such as unobtrusive +lists of another function's buffers or markers. When that function is +done with the elements, they will automatically disappear from the list. + + Weak lists are used internally, for example, to manage the list +holding the children of an extent--an extent that is unused but has a +parent will still be reclaimed, and will automatically be removed from +its parent's list of children. + + Weak lists are similar to weak hash tables (*note Weak Hash +Tables::). + + -- Function: weak-list-p object + This function returns non-`nil' if OBJECT is a weak list. + + Weak lists come in one of four types: + +`simple' + Objects in the list disappear if not referenced outside of the + list. + +`assoc' + Objects in the list disappear if they are conses and either the + car or the cdr of the cons is not referenced outside of the list. + +`key-assoc' + Objects in the list disappear if they are conses and the car is not + referenced outside of the list. + +`value-assoc' + Objects in the list disappear if they are conses and the cdr is not + referenced outside of the list. + + -- Function: make-weak-list &optional type + This function creates a new weak list of type TYPE. TYPE is a + symbol (one of `simple', `assoc', `key-assoc', or `value-assoc', + as described above) and defaults to `simple'. + + -- Function: weak-list-type weak + This function returns the type of the given weak-list object. + + -- Function: weak-list-list weak + This function returns the list contained in a weak-list object. + + -- Function: set-weak-list-list weak new-list + This function changes the list contained in a weak-list object. + + +File: lispref.info, Node: Sequences Arrays Vectors, Next: Symbols, Prev: Lists, Up: Top + +12 Sequences, Arrays, and Vectors +********************************* + +Recall that the "sequence" type is the union of four other Lisp types: +lists, vectors, bit vectors, and strings. In other words, any list is +a sequence, any vector is a sequence, any bit vector is a sequence, and +any string is a sequence. The common property that all sequences have +is that each is an ordered collection of elements. + + An "array" is a single primitive object that has a slot for each +elements. All the elements are accessible in constant time, but the +length of an existing array cannot be changed. Strings, vectors, and +bit vectors are the three types of arrays. + + A list is a sequence of elements, but it is not a single primitive +object; it is made of cons cells, one cell per element. Finding the +Nth element requires looking through N cons cells, so elements farther +from the beginning of the list take longer to access. But it is +possible to add elements to the list, or remove elements. + + The following diagram shows the relationship between these types: + + ___________________________________ + | | + | Sequence | + | ______ ______________________ | + | | | | | | + | | List | | Array | | + | | | | ________ _______ | | + | |______| | | | | | | | + | | | Vector | | String| | | + | | |________| |_______| | | + | | __________________ | | + | | | | | | + | | | Bit Vector | | | + | | |__________________| | | + | |______________________| | + |___________________________________| + + The elements of vectors and lists may be any Lisp objects. The +elements of strings are all characters. The elements of bit vectors +are the numbers 0 and 1. + +* Menu: + +* Sequence Functions:: Functions that accept any kind of sequence. +* Arrays:: Characteristics of arrays in XEmacs Lisp. +* Array Functions:: Functions specifically for arrays. +* Vectors:: Special characteristics of XEmacs Lisp vectors. +* Vector Functions:: Functions specifically for vectors. +* Bit Vectors:: Special characteristics of XEmacs Lisp bit vectors. +* Bit Vector Functions:: Functions specifically for bit vectors. + + +File: lispref.info, Node: Sequence Functions, Next: Arrays, Up: Sequences Arrays Vectors + +12.1 Sequences +============== + +In XEmacs Lisp, a "sequence" is either a list, a vector, a bit vector, +or a string. The common property that all sequences have is that each +is an ordered collection of elements. This section describes functions +that accept any kind of sequence. + + -- Function: sequencep object + Returns `t' if OBJECT is a list, vector, bit vector, or string, + `nil' otherwise. + + -- Function: copy-sequence sequence + Returns a copy of SEQUENCE. The copy is the same type of object + as the original sequence, and it has the same elements in the same + order. + + Storing a new element into the copy does not affect the original + SEQUENCE, and vice versa. However, the elements of the new + sequence are not copies; they are identical (`eq') to the elements + of the original. Therefore, changes made within these elements, as + found via the copied sequence, are also visible in the original + sequence. + + If the sequence is a string with extents or text properties, the + extents and text properties in the copy are also copied, not + shared with the original. (This means that modifying the extents + or text properties of the original will not affect the copy.) + However, the actual values of the properties are shared. *Note + Extents::, *Note Text Properties::. + + See also `append' in *Note Building Lists::, `concat' in *Note + Creating Strings::, `vconcat' in *Note Vectors::, and `bvconcat' + in *Note Bit Vectors::, for other ways to copy sequences. + + (setq bar '(1 2)) + => (1 2) + (setq x (vector 'foo bar)) + => [foo (1 2)] + (setq y (copy-sequence x)) + => [foo (1 2)] + + (eq x y) + => nil + (equal x y) + => t + (eq (elt x 1) (elt y 1)) + => t + + ;; Replacing an element of one sequence. + (aset x 0 'quux) + x => [quux (1 2)] + y => [foo (1 2)] + + ;; Modifying the inside of a shared element. + (setcar (aref x 1) 69) + x => [quux (69 2)] + y => [foo (69 2)] + + ;; Creating a bit vector. + (bit-vector 1 0 1 1 0 1 0 0) + => #*10110100 + + -- Function: length sequence + Returns the number of elements in SEQUENCE. If SEQUENCE is a cons + cell that is not a list (because the final CDR is not `nil'), a + `wrong-type-argument' error is signaled. + + (length '(1 2 3)) + => 3 + (length ()) + => 0 + (length "foobar") + => 6 + (length [1 2 3]) + => 3 + (length #*01101) + => 5 + + -- Function: elt sequence index + This function returns the element of SEQUENCE indexed by INDEX. + Legitimate values of INDEX are integers ranging from 0 up to one + less than the length of SEQUENCE. If SEQUENCE is a list, then + out-of-range values of INDEX return `nil'; otherwise, they trigger + an `args-out-of-range' error. + + (elt [1 2 3 4] 2) + => 3 + (elt '(1 2 3 4) 2) + => 3 + (char-to-string (elt "1234" 2)) + => "3" + (elt #*00010000 3) + => 1 + (elt [1 2 3 4] 4) + error-->Args out of range: [1 2 3 4], 4 + (elt [1 2 3 4] -1) + error-->Args out of range: [1 2 3 4], -1 + + This function generalizes `aref' (*note Array Functions::) and + `nth' (*note List Elements::). + + +File: lispref.info, Node: Arrays, Next: Array Functions, Prev: Sequence Functions, Up: Sequences Arrays Vectors + +12.2 Arrays +=========== + +An "array" object has slots that hold a number of other Lisp objects, +called the elements of the array. Any element of an array may be +accessed in constant time. In contrast, an element of a list requires +access time that is proportional to the position of the element in the +list. + + When you create an array, you must specify how many elements it has. +The amount of space allocated depends on the number of elements. +Therefore, it is impossible to change the size of an array once it is +created; you cannot add or remove elements. However, you can replace an +element with a different value. + + XEmacs defines three types of array, all of which are +one-dimensional: "strings", "vectors", and "bit vectors". A vector is a +general array; its elements can be any Lisp objects. A string is a +specialized array; its elements must be characters. A bit vector is +another specialized array; its elements must be bits (an integer, either +0 or 1). Each type of array has its own read syntax. *Note String +Type::, *Note Vector Type::, and *Note Bit Vector Type::. + + All kinds of array share these characteristics: + + * The first element of an array has index zero, the second element + has index 1, and so on. This is called "zero-origin" indexing. + For example, an array of four elements has indices 0, 1, 2, and 3. + + * The elements of an array may be referenced or changed with the + functions `aref' and `aset', respectively (*note Array + Functions::). + + In principle, if you wish to have an array of text characters, you +could use either a string or a vector. In practice, we always choose +strings for such applications, for four reasons: + + * They usually occupy one-fourth the space of a vector of the same + elements. (This is one-eighth the space for 64-bit machines such + as the DEC Alpha, and may also be different when MULE support is + compiled into XEmacs.) + + * Strings are printed in a way that shows the contents more clearly + as characters. + + * Strings can hold extent and text properties. *Note Extents::, + *Note Text Properties::. + + * Many of the specialized editing and I/O facilities of XEmacs + accept only strings. For example, you cannot insert a vector of + characters into a buffer the way you can insert a string. *Note + Strings and Characters::. + + By contrast, for an array of keyboard input characters (such as a key +sequence), a vector may be necessary, because many keyboard input +characters are non-printable and are represented with symbols rather +than with characters. *Note Key Sequence Input::. + + Similarly, when representing an array of bits, a bit vector has the +following advantages over a regular vector: + + * They occupy 1/32nd the space of a vector of the same elements. + (1/64th on 64-bit machines such as the DEC Alpha.) + + * Bit vectors are printed in a way that shows the contents more + clearly as bits. + + +File: lispref.info, Node: Array Functions, Next: Vectors, Prev: Arrays, Up: Sequences Arrays Vectors + +12.3 Functions that Operate on Arrays +===================================== + +In this section, we describe the functions that accept strings, vectors, +and bit vectors. + + -- Function: arrayp object + This function returns `t' if OBJECT is an array (i.e., a string, + vector, or bit vector). + + (arrayp "asdf") + => t + (arrayp [a]) + => t + (arrayp #*101) + => t + + -- Function: aref array index + This function returns the INDEXth element of ARRAY. The first + element is at index zero. + + (setq primes [2 3 5 7 11 13]) + => [2 3 5 7 11 13] + (aref primes 4) + => 11 + (elt primes 4) + => 11 + + (aref "abcdefg" 1) + => ?b + + (aref #*1101 2) + => 0 + + See also the function `elt', in *Note Sequence Functions::. + + -- Function: aset array index object + This function sets the INDEXth element of ARRAY to be OBJECT. It + returns OBJECT. + + (setq w [foo bar baz]) + => [foo bar baz] + (aset w 0 'fu) + => fu + w + => [fu bar baz] + + (setq x "asdfasfd") + => "asdfasfd" + (aset x 3 ?Z) + => ?Z + x + => "asdZasfd" + + (setq bv #*1111) + => #*1111 + (aset bv 2 0) + => 0 + bv + => #*1101 + + If ARRAY is a string and OBJECT is not a character, a + `wrong-type-argument' error results. + + -- Function: fillarray array object + This function fills the array ARRAY with OBJECT, so that each + element of ARRAY is OBJECT. It returns ARRAY. + + (setq a [a b c d e f g]) + => [a b c d e f g] + (fillarray a 0) + => [0 0 0 0 0 0 0] + a + => [0 0 0 0 0 0 0] + + (setq s "When in the course") + => "When in the course" + (fillarray s ?-) + => "------------------" + + (setq bv #*1101) + => #*1101 + (fillarray bv 0) + => #*0000 + + If ARRAY is a string and OBJECT is not a character, a + `wrong-type-argument' error results. + + The general sequence functions `copy-sequence' and `length' are +often useful for objects known to be arrays. *Note Sequence +Functions::. + + +File: lispref.info, Node: Vectors, Next: Vector Functions, Prev: Array Functions, Up: Sequences Arrays Vectors + +12.4 Vectors +============ + +Arrays in Lisp, like arrays in most languages, are blocks of memory +whose elements can be accessed in constant time. A "vector" is a +general-purpose array; its elements can be any Lisp objects. (The other +kind of array in XEmacs Lisp is the "string", whose elements must be +characters.) Vectors in XEmacs serve as obarrays (vectors of symbols), +although this is a shortcoming that should be fixed. They are also used +internally as part of the representation of a byte-compiled function; if +you print such a function, you will see a vector in it. + + In XEmacs Lisp, the indices of the elements of a vector start from +zero and count up from there. + + Vectors are printed with square brackets surrounding the elements. +Thus, a vector whose elements are the symbols `a', `b' and `a' is +printed as `[a b a]'. You can write vectors in the same way in Lisp +input. + + A vector, like a string or a number, is considered a constant for +evaluation: the result of evaluating it is the same vector. This does +not evaluate or even examine the elements of the vector. *Note +Self-Evaluating Forms::. + + Here are examples of these principles: + + (setq avector [1 two '(three) "four" [five]]) + => [1 two (quote (three)) "four" [five]] + (eval avector) + => [1 two (quote (three)) "four" [five]] + (eq avector (eval avector)) + => t + + +File: lispref.info, Node: Vector Functions, Next: Bit Vectors, Prev: Vectors, Up: Sequences Arrays Vectors + +12.5 Functions That Operate on Vectors +====================================== + +Here are some functions that relate to vectors: + + -- Function: vectorp object + This function returns `t' if OBJECT is a vector. + + (vectorp [a]) + => t + (vectorp "asdf") + => nil + + -- Function: vector &rest objects + This function creates and returns a vector whose elements are the + arguments, OBJECTS. + + (vector 'foo 23 [bar baz] "rats") + => [foo 23 [bar baz] "rats"] + (vector) + => [] + + -- Function: make-vector length object + This function returns a new vector consisting of LENGTH elements, + each initialized to OBJECT. + + (setq sleepy (make-vector 9 'Z)) + => [Z Z Z Z Z Z Z Z Z] + + -- Function: vconcat &rest sequences + This function returns a new vector containing all the elements of + the SEQUENCES. The arguments SEQUENCES may be lists, vectors, or + strings. If no SEQUENCES are given, an empty vector is returned. + + The value is a newly constructed vector that is not `eq' to any + existing vector. + + (setq a (vconcat '(A B C) '(D E F))) + => [A B C D E F] + (eq a (vconcat a)) + => nil + (vconcat) + => [] + (vconcat [A B C] "aa" '(foo (6 7))) + => [A B C 97 97 foo (6 7)] + + The `vconcat' function also allows integers as arguments. It + converts them to strings of digits, making up the decimal print + representation of the integer, and then uses the strings instead + of the original integers. *Don't use this feature; we plan to + eliminate it. If you already use this feature, change your + programs now!* The proper way to convert an integer to a decimal + number in this way is with `format' (*note Formatting Strings::) + or `number-to-string' (*note String Conversion::). + + For other concatenation functions, see `mapconcat' in *Note + Mapping Functions::, `concat' in *Note Creating Strings::, `append' + in *Note Building Lists::, and `bvconcat' in *Note Bit Vector + Functions::. + + The `append' function provides a way to convert a vector into a list +with the same elements (*note Building Lists::): + + (setq avector [1 two (quote (three)) "four" [five]]) + => [1 two (quote (three)) "four" [five]] + (append avector nil) + => (1 two (quote (three)) "four" [five]) + + +File: lispref.info, Node: Bit Vectors, Next: Bit Vector Functions, Prev: Vector Functions, Up: Sequences Arrays Vectors + +12.6 Bit Vectors +================ + +Bit vectors are specialized vectors that can only represent arrays of +1's and 0's. Bit vectors have a very efficient representation and are +useful for representing sets of boolean (true or false) values. + + There is no limit on the size of a bit vector. You could, for +example, create a bit vector with 100,000 elements if you really wanted +to. + + Bit vectors have a special printed representation consisting of `#*' +followed by the bits of the vector. For example, a bit vector whose +elements are 0, 1, 1, 0, and 1, respectively, is printed as + + #*01101 + + Bit vectors are considered constants for evaluation, like vectors, +strings, and numbers. *Note Self-Evaluating Forms::. + + +File: lispref.info, Node: Bit Vector Functions, Prev: Bit Vectors, Up: Sequences Arrays Vectors + +12.7 Functions That Operate on Bit Vectors +========================================== + +Here are some functions that relate to bit vectors: + + -- Function: bit-vector-p object + This function returns `t' if OBJECT is a bit vector. + + (bit-vector-p #*01) + => t + (bit-vector-p [0 1]) + => nil + (bit-vector-p "01") + => nil + + -- Function: bitp object + This function returns `t' if OBJECT is either 0 or 1. + + -- Function: bit-vector &rest bits + This function creates and returns a bit vector whose elements are + the arguments BITS. Each argument must be a bit, i.e. one of the + two integers 0 or 1. + + (bit-vector 0 0 0 1 0 0 0 0 1 0) + => #*0001000010 + (bit-vector) + => #* + + -- Function: make-bit-vector length bit + This function creates and returns a bit vector consisting of + LENGTH elements, each initialized to BIT, which must be one of the + two integers 0 or 1. + + (setq picket-fence (make-bit-vector 9 1)) + => #*111111111 + + -- Function: bvconcat &rest sequences + This function returns a new bit vector containing all the elements + of the SEQUENCES. The arguments SEQUENCES may be lists, vectors, + or bit vectors, all of whose elements are the integers 0 or 1. If + no SEQUENCES are given, an empty bit vector is returned. + + The value is a newly constructed bit vector that is not `eq' to any + existing bit vector. + + (setq a (bvconcat '(1 1 0) '(0 0 1))) + => #*110001 + (eq a (bvconcat a)) + => nil + (bvconcat) + => #* + (bvconcat [1 0 0 0 0] #*111 '(0 0 0 0 1)) + => #*1000011100001 + + For other concatenation functions, see `mapconcat' in *Note + Mapping Functions::, `concat' in *Note Creating Strings::, + `vconcat' in *Note Vector Functions::, and `append' in *Note + Building Lists::. + + The `append' function provides a way to convert a bit vector into a +list with the same elements (*note Building Lists::): + + (setq bv #*00001110) + => #*00001110 + (append bv nil) + => (0 0 0 0 1 1 1 0) + + +File: lispref.info, Node: Symbols, Next: Evaluation, Prev: Sequences Arrays Vectors, Up: Top + +13 Symbols +********** + +A "symbol" is an object with a unique name. This chapter describes +symbols, their components, their property lists, and how they are +created and interned. Separate chapters describe the use of symbols as +variables and as function names; see *Note Variables::, and *Note +Functions and Commands::. For the precise read syntax for symbols, see +*Note Symbol Type::. + + You can test whether an arbitrary Lisp object is a symbol with +`symbolp': + + -- Function: symbolp object + This function returns `t' if OBJECT is a symbol, `nil' otherwise. + +* Menu: + +* Symbol Components:: Symbols have names, values, function definitions + and property lists. +* Definitions:: A definition says how a symbol will be used. +* Creating Symbols:: How symbols are kept unique. +* Symbol Properties:: Each symbol has a property list + for recording miscellaneous information. + + +File: lispref.info, Node: Symbol Components, Next: Definitions, Up: Symbols + +13.1 Symbol Components +====================== + +Each symbol has four components (or "cells"), each of which references +another object: + +Print name + The "print name cell" holds a string that names the symbol for + reading and printing. See `symbol-name' in *Note Creating + Symbols::. + +Value + The "value cell" holds the current value of the symbol as a + variable. When a symbol is used as a form, the value of the form + is the contents of the symbol's value cell. See `symbol-value' in + *Note Accessing Variables::. + +Function + The "function cell" holds the function definition of the symbol. + When a symbol is used as a function, its function definition is + used in its place. This cell is also used to make a symbol stand + for a keymap or a keyboard macro, for editor command execution. + Because each symbol has separate value and function cells, + variables and function names do not conflict. See + `symbol-function' in *Note Function Cells::. + +Property list + The "property list cell" holds the property list of the symbol. + See `symbol-plist' in *Note Symbol Properties::. + + The print name cell always holds a string, and cannot be changed. +The other three cells can be set individually to any specified Lisp +object. + + The print name cell holds the string that is the name of the symbol. +Since symbols are represented textually by their names, it is important +not to have two symbols with the same name. The Lisp reader ensures +this: every time it reads a symbol, it looks for an existing symbol with +the specified name before it creates a new one. (In XEmacs Lisp, this +lookup uses a hashing algorithm and an obarray; see *Note Creating +Symbols::.) + + In normal usage, the function cell usually contains a function or +macro, as that is what the Lisp interpreter expects to see there (*note +Evaluation::). Keyboard macros (*note Keyboard Macros::), keymaps +(*note Keymaps::) and autoload objects (*note Autoloading::) are also +sometimes stored in the function cell of symbols. We often refer to +"the function `foo'" when we really mean the function stored in the +function cell of the symbol `foo'. We make the distinction only when +necessary. + + The property list cell normally should hold a correctly formatted +property list (*note Property Lists::), as a number of functions expect +to see a property list there. + + The function cell or the value cell may be "void", which means that +the cell does not reference any object. (This is not the same thing as +holding the symbol `void', nor the same as holding the symbol `nil'.) +Examining a cell that is void results in an error, such as `Symbol's +value as variable is void'. + + The four functions `symbol-name', `symbol-value', `symbol-plist', +and `symbol-function' return the contents of the four cells of a +symbol. Here as an example we show the contents of the four cells of +the symbol `buffer-file-name': + + (symbol-name 'buffer-file-name) + => "buffer-file-name" + (symbol-value 'buffer-file-name) + => "/gnu/elisp/symbols.texi" + (symbol-plist 'buffer-file-name) + => (variable-documentation 29529) + (symbol-function 'buffer-file-name) + => # + +Because this symbol is the variable which holds the name of the file +being visited in the current buffer, the value cell contents we see are +the name of the source file of this chapter of the XEmacs Lisp Reference +Manual. The property list cell contains the list +`(variable-documentation 29529)' which tells the documentation +functions where to find the documentation string for the variable +`buffer-file-name' in the `DOC' file. (29529 is the offset from the +beginning of the `DOC' file to where that documentation string begins.) +The function cell contains the function for returning the name of the +file. `buffer-file-name' names a primitive function, which has no read +syntax and prints in hash notation (*note Primitive Function Type::). A +symbol naming a function written in Lisp would have a lambda expression +(or a byte-code object) in this cell. + + +File: lispref.info, Node: Definitions, Next: Creating Symbols, Prev: Symbol Components, Up: Symbols + +13.2 Defining Symbols +===================== + +A "definition" in Lisp is a special form that announces your intention +to use a certain symbol in a particular way. In XEmacs Lisp, you can +define a symbol as a variable, or define it as a function (or macro), +or both independently. + + A definition construct typically specifies a value or meaning for the +symbol for one kind of use, plus documentation for its meaning when used +in this way. Thus, when you define a symbol as a variable, you can +supply an initial value for the variable, plus documentation for the +variable. + + `defvar' and `defconst' are special forms that define a symbol as a +global variable. They are documented in detail in *Note Defining +Variables::. + + `defun' defines a symbol as a function, creating a lambda expression +and storing it in the function cell of the symbol. This lambda +expression thus becomes the function definition of the symbol. (The +term "function definition", meaning the contents of the function cell, +is derived from the idea that `defun' gives the symbol its definition +as a function.) `defsubst', `define-function' and `defalias' are other +ways of defining a function. *Note Functions and Commands::. + + `defmacro' defines a symbol as a macro. It creates a macro object +and stores it in the function cell of the symbol. Note that a given +symbol can be a macro or a function, but not both at once, because both +macro and function definitions are kept in the function cell, and that +cell can hold only one Lisp object at any given time. *Note Macros::. + + In XEmacs Lisp, a definition is not required in order to use a symbol +as a variable or function. Thus, you can make a symbol a global +variable with `setq', whether you define it first or not. The real +purpose of definitions is to guide programmers and programming tools. +They inform programmers who read the code that certain symbols are +_intended_ to be used as variables, or as functions. In addition, +utilities such as `etags' and `make-docfile' recognize definitions, and +add appropriate information to tag tables and the `DOC' file. *Note +Accessing Documentation::. + + +File: lispref.info, Node: Creating Symbols, Next: Symbol Properties, Prev: Definitions, Up: Symbols + +13.3 Creating and Interning Symbols +=================================== + +To understand how symbols are created in XEmacs Lisp, you must know how +Lisp reads them. Lisp must ensure that it finds the same symbol every +time it reads the same set of characters. Failure to do so would cause +complete confusion. + + When the Lisp reader encounters a symbol, it reads all the characters +of the name. Then it "hashes" those characters to find an index in a +table called an "obarray". Hashing is an efficient method of looking +something up. For example, instead of searching a telephone book cover +to cover when looking up Jan Jones, you start with the J's and go from +there. That is a simple version of hashing. Each element of the +obarray is a "bucket" which holds all the symbols with a given hash +code; to look for a given name, it is sufficient to look through all +the symbols in the bucket for that name's hash code. + + If a symbol with the desired name is found, the reader uses that +symbol. If the obarray does not contain a symbol with that name, the +reader makes a new symbol and adds it to the obarray. Finding or adding +a symbol with a certain name is called "interning" it, and the symbol +is then called an "interned symbol". + + Interning ensures that each obarray has just one symbol with any +particular name. Other like-named symbols may exist, but not in the +same obarray. Thus, the reader gets the same symbols for the same +names, as long as you keep reading with the same obarray. + + No obarray contains all symbols; in fact, some symbols are not in any +obarray. They are called "uninterned symbols". An uninterned symbol +has the same four cells as other symbols; however, the only way to gain +access to it is by finding it in some other object or as the value of a +variable. + + In XEmacs Lisp, an obarray is actually a vector. Each element of the +vector is a bucket; its value is either an interned symbol whose name +hashes to that bucket, or 0 if the bucket is empty. Each interned +symbol has an internal link (invisible to the user) to the next symbol +in the bucket. Because these links are invisible, there is no way to +find all the symbols in an obarray except using `mapatoms' (below). +The order of symbols in a bucket is not significant. + + In an empty obarray, every element is 0, and you can create an +obarray with `(make-vector LENGTH 0)'. *This is the only valid way to +create an obarray.* Prime numbers as lengths tend to result in good +hashing; lengths one less than a power of two are also good. + + *Do not try to put symbols in an obarray yourself.* This does not +work--only `intern' can enter a symbol in an obarray properly. *Do not +try to intern one symbol in two obarrays.* This would garble both +obarrays, because a symbol has just one slot to hold the following +symbol in the obarray bucket. The results would be unpredictable. + + It is possible for two different symbols to have the same name in +different obarrays; these symbols are not `eq' or `equal'. However, +this normally happens only as part of the abbrev mechanism (*note +Abbrevs::). + + Common Lisp note: In Common Lisp, a single symbol may be interned + in several obarrays. + + Most of the functions below take a name and sometimes an obarray as +arguments. A `wrong-type-argument' error is signaled if the name is +not a string, or if the obarray is not a vector. + + -- Function: symbol-name symbol + This function returns the string that is SYMBOL's name. For + example: + + (symbol-name 'foo) + => "foo" + + Changing the string by substituting characters, etc, does change + the name of the symbol, but fails to update the obarray, so don't + do it! + + -- Function: make-symbol name + This function returns a newly-allocated, uninterned symbol whose + name is NAME (which must be a string). Its value and function + definition are void, and its property list is `nil'. In the + example below, the value of `sym' is not `eq' to `foo' because it + is a distinct uninterned symbol whose name is also `foo'. + + (setq sym (make-symbol "foo")) + => foo + (eq sym 'foo) + => nil + + -- Function: intern name &optional obarray + This function returns the interned symbol whose name is NAME. If + there is no such symbol in the obarray OBARRAY, `intern' creates a + new one, adds it to the obarray, and returns it. If OBARRAY is + omitted, the value of the global variable `obarray' is used. + + (setq sym (intern "foo")) + => foo + (eq sym 'foo) + => t + + (setq sym1 (intern "foo" other-obarray)) + => foo + (eq sym 'foo) + => nil + + -- Function: intern-soft name &optional obarray + This function returns the symbol in OBARRAY whose name is NAME, or + `nil' if OBARRAY has no symbol with that name. Therefore, you can + use `intern-soft' to test whether a symbol with a given name is + already interned. If OBARRAY is omitted, the value of the global + variable `obarray' is used. + + (intern-soft "frazzle") ; No such symbol exists. + => nil + (make-symbol "frazzle") ; Create an uninterned one. + => frazzle + (intern-soft "frazzle") ; That one cannot be found. + => nil + (setq sym (intern "frazzle")) ; Create an interned one. + => frazzle + (intern-soft "frazzle") ; That one can be found! + => frazzle + (eq sym 'frazzle) ; And it is the same one. + => t + + -- Variable: obarray + This variable is the standard obarray for use by `intern' and + `read'. + + -- Function: mapatoms function &optional obarray + This function calls FUNCTION for each symbol in the obarray + OBARRAY. It returns `nil'. If OBARRAY is omitted, it defaults to + the value of `obarray', the standard obarray for ordinary symbols. + + (setq count 0) + => 0 + (defun count-syms (s) + (setq count (1+ count))) + => count-syms + (mapatoms 'count-syms) + => nil + count + => 1871 + + See `documentation' in *Note Accessing Documentation::, for another + example using `mapatoms'. + + -- Function: unintern symbol &optional obarray + This function deletes SYMBOL from the obarray OBARRAY. If + `symbol' is not actually in the obarray, `unintern' does nothing. + If OBARRAY is `nil', the current obarray is used. + + If you provide a string instead of a symbol as SYMBOL, it stands + for a symbol name. Then `unintern' deletes the symbol (if any) in + the obarray which has that name. If there is no such symbol, + `unintern' does nothing. + + If `unintern' does delete a symbol, it returns `t'. Otherwise it + returns `nil'. + + +File: lispref.info, Node: Symbol Properties, Prev: Creating Symbols, Up: Symbols + +13.4 Symbol Properties +====================== + +A "property list" ("plist" for short) is a list of paired elements, +often stored in the property list cell of a symbol. Each of the pairs +associates a property name (usually a symbol) with a property or value. +Property lists are generally used to record information about a +symbol, such as its documentation as a variable, the name of the file +where it was defined, or perhaps even the grammatical class of the +symbol (representing a word) in a language-understanding system. + + Some objects which are not symbols also have property lists +associated with them, and XEmacs provides a full complement of +functions for working with property lists. *Note Property Lists::. + + The property names and values in a property list can be any Lisp +objects, but the names are usually symbols. They are compared using +`eq'. Here is an example of a property list, found on the symbol +`progn' when the compiler is loaded: + + (lisp-indent-function 0 byte-compile byte-compile-progn) + +Here `lisp-indent-function' and `byte-compile' are property names, and +the other two elements are the corresponding values. + +* Menu: + +* Plists and Alists:: Comparison of the advantages of property + lists and association lists. +* Object Plists:: Functions to access objects' property lists. +* Other Plists:: Accessing property lists stored elsewhere. + + +File: lispref.info, Node: Plists and Alists, Next: Object Plists, Up: Symbol Properties + +13.4.1 Property Lists and Association Lists +------------------------------------------- + +Association lists (*note Association Lists::) are very similar to +property lists. In contrast to association lists, the order of the +pairs in the property list is not significant since the property names +must be distinct. + + Property lists are better than association lists for attaching +information to various Lisp function names or variables. If all the +associations are recorded in one association list, the program will need +to search that entire list each time a function or variable is to be +operated on. By contrast, if the information is recorded in the +property lists of the function names or variables themselves, each +search will scan only the length of one property list, which is usually +short. This is why the documentation for a variable is recorded in a +property named `variable-documentation'. The byte compiler likewise +uses properties to record those functions needing special treatment. + + However, association lists have their own advantages. Depending on +your application, it may be faster to add an association to the front of +an association list than to update a property. All properties for a +symbol are stored in the same property list, so there is a possibility +of a conflict between different uses of a property name. (For this +reason, it is a good idea to choose property names that are probably +unique, such as by including the name of the library in the property +name.) An association list may be used like a stack where associations +are pushed on the front of the list and later discarded; this is not +possible with a property list. + + +File: lispref.info, Node: Object Plists, Next: Other Plists, Prev: Plists and Alists, Up: Symbol Properties + +13.4.2 Property List Functions for Objects +------------------------------------------ + +Once upon a time, only symbols had property lists. Now, several other +object types, including strings, extents, faces and glyphs also have +property lists. + + -- Function: symbol-plist symbol + This function returns the property list of SYMBOL. + + -- Function: object-plist object + This function returns the property list of OBJECT. If OBJECT is a + symbol, this is identical to `symbol-plist'. + + -- Function: setplist symbol plist + This function sets SYMBOL's property list to PLIST. Normally, + PLIST should be a well-formed property list, but this is not + enforced. + + (setplist 'foo '(a 1 b (2 3) c nil)) + => (a 1 b (2 3) c nil) + (symbol-plist 'foo) + => (a 1 b (2 3) c nil) + + For symbols in special obarrays, which are not used for ordinary + purposes, it may make sense to use the property list cell in a + nonstandard fashion; in fact, the abbrev mechanism does so (*note + Abbrevs::). But generally, its use is discouraged. Use `put' + instead. `setplist' can only be used with symbols, not other + object types. + + -- Function: get object property &optional default + This function finds the value of the property named PROPERTY in + OBJECT's property list. If there is no such property, `default' + (which itself defaults to `nil') is returned. + + PROPERTY is compared with the existing properties using `eq', so + any object is a legitimate property. + + See `put' for an example. + + -- Function: put object property value + This function puts VALUE onto OBJECT's property list under the + property name PROPERTY, replacing any previous property value. + The `put' function returns VALUE. + + (put 'fly 'verb 'transitive) + =>'transitive + (put 'fly 'noun '(a buzzing little bug)) + => (a buzzing little bug) + (get 'fly 'verb) + => transitive + (object-plist 'fly) + => (verb transitive noun (a buzzing little bug)) + + -- Function: remprop object property + This function removes the entry for PROPERTY from the property + list of OBJECT. It returns `t' if the property was indeed found + and removed, or `nil' if there was no such property. (This + function was probably omitted from Emacs originally because, since + `get' did not allow a DEFAULT, it was very difficult to + distinguish between a missing property and a property whose value + was `nil'; thus, setting a property to `nil' was close enough to + `remprop' for most purposes.) + + +File: lispref.info, Node: Other Plists, Prev: Object Plists, Up: Symbol Properties + +13.4.3 Property Lists Not Associated with Objects +------------------------------------------------- + +These functions are useful for manipulating property lists that are +stored in places other than symbols: + + -- Function: getf plist property &optional default + This returns the value of the PROPERTY property stored in the + property list PLIST. For example, + + (getf '(foo 4) 'foo) + => 4 + + -- Macro: putf plist property value + This stores VALUE as the value of the PROPERTY property in the + property list PLIST. It may modify PLIST destructively, or it may + construct a new list structure without altering the old. The + function returns the modified property list, so you can store that + back in the place where you got PLIST. For example, + + (setq my-plist '(bar t foo 4)) + => (bar t foo 4) + (setq my-plist (putf my-plist 'foo 69)) + => (bar t foo 69) + (setq my-plist (putf my-plist 'quux '(a))) + => (quux (a) bar t foo 5) + + -- Function: plists-eq a b + This function returns non-`nil' if property lists A and B are + `eq'. This means that the property lists have the same values for + all the same properties, where comparison between values is done + using `eq'. + + -- Function: plists-equal a b + This function returns non-`nil' if property lists A and B are + `equal'. + + Both of the above functions do order-insensitive comparisons. + + (plists-eq '(a 1 b 2 c nil) '(b 2 a 1)) + => t + (plists-eq '(foo "hello" bar "goodbye") '(bar "goodbye" foo "hello")) + => nil + (plists-equal '(foo "hello" bar "goodbye") '(bar "goodbye" foo "hello")) + => t + + +File: lispref.info, Node: Evaluation, Next: Control Structures, Prev: Symbols, Up: Top + +14 Evaluation +************* + +The "evaluation" of expressions in XEmacs Lisp is performed by the +"Lisp interpreter"--a program that receives a Lisp object as input and +computes its "value as an expression". How it does this depends on the +data type of the object, according to rules described in this chapter. +The interpreter runs automatically to evaluate portions of your +program, but can also be called explicitly via the Lisp primitive +function `eval'. + +* Menu: + +* Intro Eval:: Evaluation in the scheme of things. +* Eval:: How to invoke the Lisp interpreter explicitly. +* Forms:: How various sorts of objects are evaluated. +* Quoting:: Avoiding evaluation (to put constants in the program). + + +File: lispref.info, Node: Intro Eval, Next: Eval, Up: Evaluation + +14.1 Introduction to Evaluation +=============================== + +The Lisp interpreter, or evaluator, is the program that computes the +value of an expression that is given to it. When a function written in +Lisp is called, the evaluator computes the value of the function by +evaluating the expressions in the function body. Thus, running any +Lisp program really means running the Lisp interpreter. + + How the evaluator handles an object depends primarily on the data +type of the object. + + A Lisp object that is intended for evaluation is called an +"expression" or a "form". The fact that expressions are data objects +and not merely text is one of the fundamental differences between +Lisp-like languages and typical programming languages. Any object can +be evaluated, but in practice only numbers, symbols, lists and strings +are evaluated very often. + + It is very common to read a Lisp expression and then evaluate the +expression, but reading and evaluation are separate activities, and +either can be performed alone. Reading per se does not evaluate +anything; it converts the printed representation of a Lisp object to the +object itself. It is up to the caller of `read' whether this object is +a form to be evaluated, or serves some entirely different purpose. +*Note Input Functions::. + + Do not confuse evaluation with command key interpretation. The +editor command loop translates keyboard input into a command (an +interactively callable function) using the active keymaps, and then +uses `call-interactively' to invoke the command. The execution of the +command itself involves evaluation if the command is written in Lisp, +but that is not a part of command key interpretation itself. *Note +Command Loop::. + + Evaluation is a recursive process. That is, evaluation of a form may +call `eval' to evaluate parts of the form. For example, evaluation of +a function call first evaluates each argument of the function call, and +then evaluates each form in the function body. Consider evaluation of +the form `(car x)': the subform `x' must first be evaluated +recursively, so that its value can be passed as an argument to the +function `car'. + + Evaluation of a function call ultimately calls the function specified +in it. *Note Functions and Commands::. The execution of the function +may itself work by evaluating the function definition; or the function +may be a Lisp primitive implemented in C, or it may be a byte-compiled +function (*note Byte Compilation::). + + The evaluation of forms takes place in a context called the +"environment", which consists of the current values and bindings of all +Lisp variables.(1) Whenever the form refers to a variable without +creating a new binding for it, the value of the binding in the current +environment is used. *Note Variables::. + + Evaluation of a form may create new environments for recursive +evaluation by binding variables (*note Local Variables::). These +environments are temporary and vanish by the time evaluation of the form +is complete. The form may also make changes that persist; these changes +are called "side effects". An example of a form that produces side +effects is `(setq foo 1)'. + + The details of what evaluation means for each kind of form are +described below (*note Forms::). + + ---------- Footnotes ---------- + + (1) This definition of "environment" is specifically not intended to +include all the data that can affect the result of a program. + + +File: lispref.info, Node: Eval, Next: Forms, Prev: Intro Eval, Up: Evaluation + +14.2 Eval +========= + +Most often, forms are evaluated automatically, by virtue of their +occurrence in a program being run. On rare occasions, you may need to +write code that evaluates a form that is computed at run time, such as +after reading a form from text being edited or getting one from a +property list. On these occasions, use the `eval' function. + + *Please note:* it is generally cleaner and more flexible to call +functions that are stored in data structures, rather than to evaluate +expressions stored in data structures. Using functions provides the +ability to pass information to them as arguments. + + The functions and variables described in this section evaluate forms, +specify limits to the evaluation process, or record recently returned +values. Loading a file also does evaluation (*note Loading::). + + -- Function: eval form + This is the basic function for performing evaluation. It evaluates + FORM in the current environment and returns the result. How the + evaluation proceeds depends on the type of the object (*note + Forms::). + + Since `eval' is a function, the argument expression that appears + in a call to `eval' is evaluated twice: once as preparation before + `eval' is called, and again by the `eval' function itself. Here + is an example: + + (setq foo 'bar) + => bar + (setq bar 'baz) + => baz + ;; `eval' receives argument `bar', which is the value of `foo' + (eval foo) + => baz + (eval 'foo) + => bar + + The number of currently active calls to `eval' is limited to + `max-lisp-eval-depth' (see below). + + -- Command: eval-region start end &optional stream + This function evaluates the forms in the current buffer in the + region defined by the positions START and END. It reads forms from + the region and calls `eval' on them until the end of the region is + reached, or until an error is signaled and not handled. + + If STREAM is supplied, `standard-output' is bound to it during the + evaluation. + + You can use the variable `load-read-function' to specify a function + for `eval-region' to use instead of `read' for reading + expressions. *Note How Programs Do Loading::. + + `eval-region' always returns `nil'. + + -- Command: eval-buffer buffer &optional stream + This is like `eval-region' except that it operates on the whole + contents of BUFFER. + + -- Variable: max-lisp-eval-depth + This variable defines the maximum depth allowed in calls to `eval', + `apply', and `funcall' before an error is signaled (with error + message `"Lisp nesting exceeds max-lisp-eval-depth"'). This counts + internal uses of those functions, such as for calling the functions + mentioned in Lisp expressions, and recursive evaluation of + function call arguments and function body forms. + + This limit, with the associated error when it is exceeded, is one + way that Lisp avoids infinite recursion on an ill-defined function. + + The default value of this variable is 1000. If you set it to a + value less than 100, Lisp will reset it to 100 if the given value + is reached. + + `max-specpdl-size' provides another limit on nesting. *Note Local + Variables::. + + -- Variable: values + The value of this variable is a list of the values returned by all + the expressions that were read from buffers (including the + minibuffer), evaluated, and printed. The elements are ordered + most recent first. + + (setq x 1) + => 1 + (list 'A (1+ 2) auto-save-default) + => (A 3 t) + values + => ((A 3 t) 1 ...) + + This variable is useful for referring back to values of forms + recently evaluated. It is generally a bad idea to print the value + of `values' itself, since this may be very long. Instead, examine + particular elements, like this: + + ;; Refer to the most recent evaluation result. + (nth 0 values) + => (A 3 t) + ;; That put a new element on, + ;; so all elements move back one. + (nth 1 values) + => (A 3 t) + ;; This gets the element that was next-to-most-recent + ;; before this example. + (nth 3 values) + => 1 + + +File: lispref.info, Node: Forms, Next: Quoting, Prev: Eval, Up: Evaluation + +14.3 Kinds of Forms +=================== + +A Lisp object that is intended to be evaluated is called a "form". How +XEmacs evaluates a form depends on its data type. XEmacs has three +different kinds of form that are evaluated differently: symbols, lists, +and "all other types". This section describes all three kinds, +starting with "all other types" which are self-evaluating forms. + +* Menu: + +* Self-Evaluating Forms:: Forms that evaluate to themselves. +* Symbol Forms:: Symbols evaluate as variables. +* Classifying Lists:: How to distinguish various sorts of list forms. +* Function Indirection:: When a symbol appears as the car of a list, + we find the real function via the symbol. +* Function Forms:: Forms that call functions. +* Macro Forms:: Forms that call macros. +* Special Forms:: ``Special forms'' are idiosyncratic primitives, + most of them extremely important. +* Autoloading:: Functions set up to load files + containing their real definitions. + + +File: lispref.info, Node: Self-Evaluating Forms, Next: Symbol Forms, Up: Forms + +14.3.1 Self-Evaluating Forms +---------------------------- + +A "self-evaluating form" is any form that is not a list or symbol. +Self-evaluating forms evaluate to themselves: the result of evaluation +is the same object that was evaluated. Thus, the number 25 evaluates to +25, and the string `"foo"' evaluates to the string `"foo"'. Likewise, +evaluation of a vector does not cause evaluation of the elements of the +vector--it returns the same vector with its contents unchanged. + + '123 ; An object, shown without evaluation. + => 123 + 123 ; Evaluated as usual--result is the same. + => 123 + (eval '123) ; Evaluated "by hand"--result is the same. + => 123 + (eval (eval '123)) ; Evaluating twice changes nothing. + => 123 + + It is common to write numbers, characters, strings, and even vectors +in Lisp code, taking advantage of the fact that they self-evaluate. +However, it is quite unusual to do this for types that lack a read +syntax, because there's no way to write them textually. It is possible +to construct Lisp expressions containing these types by means of a Lisp +program. Here is an example: + + ;; Build an expression containing a buffer object. + (setq buffer (list 'print (current-buffer))) + => (print #) + ;; Evaluate it. + (eval buffer) + -| # + => # + + +File: lispref.info, Node: Symbol Forms, Next: Classifying Lists, Prev: Self-Evaluating Forms, Up: Forms + +14.3.2 Symbol Forms +------------------- + +When a symbol is evaluated, it is treated as a variable. The result is +the variable's value, if it has one. If it has none (if its value cell +is void), an error is signaled. For more information on the use of +variables, see *Note Variables::. + + In the following example, we set the value of a symbol with `setq'. +Then we evaluate the symbol, and get back the value that `setq' stored. + + (setq a 123) + => 123 + (eval 'a) + => 123 + a + => 123 + + The symbols `nil' and `t' are treated specially, so that the value +of `nil' is always `nil', and the value of `t' is always `t'; you +cannot set or bind them to any other values. Thus, these two symbols +act like self-evaluating forms, even though `eval' treats them like any +other symbol. + + +File: lispref.info, Node: Classifying Lists, Next: Function Indirection, Prev: Symbol Forms, Up: Forms + +14.3.3 Classification of List Forms +----------------------------------- + +A form that is a nonempty list is either a function call, a macro call, +or a special form, according to its first element. These three kinds +of forms are evaluated in different ways, described below. The +remaining list elements constitute the "arguments" for the function, +macro, or special form. + + The first step in evaluating a nonempty list is to examine its first +element. This element alone determines what kind of form the list is +and how the rest of the list is to be processed. The first element is +_not_ evaluated, as it would be in some Lisp dialects such as Scheme. + + +File: lispref.info, Node: Function Indirection, Next: Function Forms, Prev: Classifying Lists, Up: Forms + +14.3.4 Symbol Function Indirection +---------------------------------- + +If the first element of the list is a symbol then evaluation examines +the symbol's function cell, and uses its contents instead of the +original symbol. If the contents are another symbol, this process, +called "symbol function indirection", is repeated until it obtains a +non-symbol. *Note Function Names::, for more information about using a +symbol as a name for a function stored in the function cell of the +symbol. + + One possible consequence of this process is an infinite loop, in the +event that a symbol's function cell refers to the same symbol. Or a +symbol may have a void function cell, in which case the subroutine +`symbol-function' signals a `void-function' error. But if neither of +these things happens, we eventually obtain a non-symbol, which ought to +be a function or other suitable object. + + More precisely, we should now have a Lisp function (a lambda +expression), a byte-code function, a primitive function, a Lisp macro, a +special form, or an autoload object. Each of these types is a case +described in one of the following sections. If the object is not one of +these types, the error `invalid-function' is signaled. + + The following example illustrates the symbol indirection process. We +use `fset' to set the function cell of a symbol and `symbol-function' +to get the function cell contents (*note Function Cells::). +Specifically, we store the symbol `car' into the function cell of +`first', and the symbol `first' into the function cell of `erste'. + + ;; Build this function cell linkage: + ;; ------------- ----- ------- ------- + ;; | # | <-- | car | <-- | first | <-- | erste | + ;; ------------- ----- ------- ------- + + (symbol-function 'car) + => # + (fset 'first 'car) + => car + (fset 'erste 'first) + => first + (erste '(1 2 3)) ; Call the function referenced by `erste'. + => 1 + + By contrast, the following example calls a function without any +symbol function indirection, because the first element is an anonymous +Lisp function, not a symbol. + + ((lambda (arg) (erste arg)) + '(1 2 3)) + => 1 + +Executing the function itself evaluates its body; this does involve +symbol function indirection when calling `erste'. + + The built-in function `indirect-function' provides an easy way to +perform symbol function indirection explicitly. + + -- Function: indirect-function object + This function returns the meaning of OBJECT as a function. If + OBJECT is a symbol, then it finds OBJECT's function definition and + starts over with that value. If OBJECT is not a symbol, then it + returns OBJECT itself. + + Here is how you could define `indirect-function' in Lisp: + + (defun indirect-function (function) + (if (symbolp function) + (indirect-function (symbol-function function)) + function)) + + +File: lispref.info, Node: Function Forms, Next: Macro Forms, Prev: Function Indirection, Up: Forms + +14.3.5 Evaluation of Function Forms +----------------------------------- + +If the first element of a list being evaluated is a Lisp function +object, byte-code object or primitive function object, then that list is +a "function call". For example, here is a call to the function `+': + + (+ 1 x) + + The first step in evaluating a function call is to evaluate the +remaining elements of the list from left to right. The results are the +actual argument values, one value for each list element. The next step +is to call the function with this list of arguments, effectively using +the function `apply' (*note Calling Functions::). If the function is +written in Lisp, the arguments are used to bind the argument variables +of the function (*note Lambda Expressions::); then the forms in the +function body are evaluated in order, and the value of the last body +form becomes the value of the function call. + + +File: lispref.info, Node: Macro Forms, Next: Special Forms, Prev: Function Forms, Up: Forms + +14.3.6 Lisp Macro Evaluation +---------------------------- + +If the first element of a list being evaluated is a macro object, then +the list is a "macro call". When a macro call is evaluated, the +elements of the rest of the list are _not_ initially evaluated. +Instead, these elements themselves are used as the arguments of the +macro. The macro definition computes a replacement form, called the +"expansion" of the macro, to be evaluated in place of the original +form. The expansion may be any sort of form: a self-evaluating +constant, a symbol, or a list. If the expansion is itself a macro call, +this process of expansion repeats until some other sort of form results. + + Ordinary evaluation of a macro call finishes by evaluating the +expansion. However, the macro expansion is not necessarily evaluated +right away, or at all, because other programs also expand macro calls, +and they may or may not evaluate the expansions. + + Normally, the argument expressions are not evaluated as part of +computing the macro expansion, but instead appear as part of the +expansion, so they are computed when the expansion is computed. + + For example, given a macro defined as follows: + + (defmacro cadr (x) + (list 'car (list 'cdr x))) + +an expression such as `(cadr (assq 'handler list))' is a macro call, +and its expansion is: + + (car (cdr (assq 'handler list))) + +Note that the argument `(assq 'handler list)' appears in the expansion. + + *Note Macros::, for a complete description of XEmacs Lisp macros. + + +File: lispref.info, Node: Special Forms, Next: Autoloading, Prev: Macro Forms, Up: Forms + +14.3.7 Special Forms +-------------------- + +A "special form" is a primitive function specially marked so that its +arguments are not all evaluated. Most special forms define control +structures or perform variable bindings--things which functions cannot +do. + + Each special form has its own rules for which arguments are evaluated +and which are used without evaluation. Whether a particular argument is +evaluated may depend on the results of evaluating other arguments. + + Here is a list, in alphabetical order, of all of the special forms in +XEmacs Lisp with a reference to where each is described. + +`and' + *note Combining Conditions:: + +`catch' + *note Catch and Throw:: + +`cond' + *note Conditionals:: + +`condition-case' + *note Handling Errors:: + +`defconst' + *note Defining Variables:: + +`defmacro' + *note Defining Macros:: + +`defun' + *note Defining Functions:: + +`defvar' + *note Defining Variables:: + +`function' + *note Anonymous Functions:: + +`if' + *note Conditionals:: + +`interactive' + *note Interactive Call:: + +`let' +`let*' + *note Local Variables:: + +`or' + *note Combining Conditions:: + +`prog1' +`prog2' +`progn' + *note Sequencing:: + +`quote' + *note Quoting:: + +`save-current-buffer' + *note Excursions:: + +`save-excursion' + *note Excursions:: + +`save-restriction' + *note Narrowing:: + +`save-selected-window' + *note Excursions:: + +`save-window-excursion' + *note Window Configurations:: + +`setq' + *note Setting Variables:: + +`setq-default' + *note Creating Buffer-Local:: + +`unwind-protect' + *note Nonlocal Exits:: + +`while' + *note Iteration:: + +`with-output-to-temp-buffer' + *note Temporary Displays:: + + Common Lisp note: here are some comparisons of special forms in + XEmacs Lisp and Common Lisp. `setq', `if', and `catch' are + special forms in both XEmacs Lisp and Common Lisp. `defun' is a + special form in XEmacs Lisp, but a macro in Common Lisp. + `save-excursion' is a special form in XEmacs Lisp, but doesn't + exist in Common Lisp. `throw' is a special form in Common Lisp + (because it must be able to throw multiple values), but it is a + function in XEmacs Lisp (which doesn't have multiple values). + + +File: lispref.info, Node: Autoloading, Prev: Special Forms, Up: Forms + +14.3.8 Autoloading +------------------ + +The "autoload" feature allows you to call a function or macro whose +function definition has not yet been loaded into XEmacs. It specifies +which file contains the definition. When an autoload object appears as +a symbol's function definition, calling that symbol as a function +automatically loads the specified file; then it calls the real +definition loaded from that file. *Note Autoload::. + + +File: lispref.info, Node: Quoting, Prev: Forms, Up: Evaluation + +14.4 Quoting +============ + +The special form `quote' returns its single argument, as written, +without evaluating it. This provides a way to include constant symbols +and lists, which are not self-evaluating objects, in a program. (It is +not necessary to quote self-evaluating objects such as numbers, strings, +and vectors.) + + -- Special Form: quote object + This special form returns OBJECT, without evaluating it. + + Because `quote' is used so often in programs, Lisp provides a +convenient read syntax for it. An apostrophe character (`'') followed +by a Lisp object (in read syntax) expands to a list whose first element +is `quote', and whose second element is the object. Thus, the read +syntax `'x' is an abbreviation for `(quote x)'. + + Here are some examples of expressions that use `quote': + + (quote (+ 1 2)) + => (+ 1 2) + (quote foo) + => foo + 'foo + => foo + ''foo + => (quote foo) + '(quote foo) + => (quote foo) + ['foo] + => [(quote foo)] + + Other quoting constructs include `function' (*note Anonymous +Functions::), which causes an anonymous lambda expression written in +Lisp to be compiled, and ``' (*note Backquote::), which is used to quote +only part of a list, while computing and substituting other parts. + + +File: lispref.info, Node: Control Structures, Next: Variables, Prev: Evaluation, Up: Top + +15 Control Structures +********************* + +A Lisp program consists of expressions or "forms" (*note Forms::). We +control the order of execution of the forms by enclosing them in +"control structures". Control structures are special forms which +control when, whether, or how many times to execute the forms they +contain. + + The simplest order of execution is sequential execution: first form +A, then form B, and so on. This is what happens when you write several +forms in succession in the body of a function, or at top level in a +file of Lisp code--the forms are executed in the order written. We +call this "textual order". For example, if a function body consists of +two forms A and B, evaluation of the function evaluates first A and +then B, and the function's value is the value of B. + + Explicit control structures make possible an order of execution other +than sequential. + + XEmacs Lisp provides several kinds of control structure, including +other varieties of sequencing, conditionals, iteration, and (controlled) +jumps--all discussed below. The built-in control structures are +special forms since their subforms are not necessarily evaluated or not +evaluated sequentially. You can use macros to define your own control +structure constructs (*note Macros::). + +* Menu: + +* Sequencing:: Evaluation in textual order. +* Conditionals:: `if', `cond'. +* Combining Conditions:: `and', `or', `not'. +* Iteration:: `while' loops. +* Nonlocal Exits:: Jumping out of a sequence. + + +File: lispref.info, Node: Sequencing, Next: Conditionals, Up: Control Structures + +15.1 Sequencing +=============== + +Evaluating forms in the order they appear is the most common way +control passes from one form to another. In some contexts, such as in a +function body, this happens automatically. Elsewhere you must use a +control structure construct to do this: `progn', the simplest control +construct of Lisp. + + A `progn' special form looks like this: + + (progn A B C ...) + +and it says to execute the forms A, B, C and so on, in that order. +These forms are called the body of the `progn' form. The value of the +last form in the body becomes the value of the entire `progn'. + + In the early days of Lisp, `progn' was the only way to execute two +or more forms in succession and use the value of the last of them. But +programmers found they often needed to use a `progn' in the body of a +function, where (at that time) only one form was allowed. So the body +of a function was made into an "implicit `progn'": several forms are +allowed just as in the body of an actual `progn'. Many other control +structures likewise contain an implicit `progn'. As a result, `progn' +is not used as often as it used to be. It is needed now most often +inside an `unwind-protect', `and', `or', or in the THEN-part of an `if'. + + -- Special Form: progn forms... + This special form evaluates all of the FORMS, in textual order, + returning the result of the final form. + + (progn (print "The first form") + (print "The second form") + (print "The third form")) + -| "The first form" + -| "The second form" + -| "The third form" + => "The third form" + + Two other control constructs likewise evaluate a series of forms but +return a different value: + + -- Special Form: prog1 form1 forms... + This special form evaluates FORM1 and all of the FORMS, in textual + order, returning the result of FORM1. + + (prog1 (print "The first form") + (print "The second form") + (print "The third form")) + -| "The first form" + -| "The second form" + -| "The third form" + => "The first form" + + Here is a way to remove the first element from a list in the + variable `x', then return the value of that former element: + + (prog1 (car x) (setq x (cdr x))) + + -- Special Form: prog2 form1 form2 forms... + This special form evaluates FORM1, FORM2, and all of the following + FORMS, in textual order, returning the result of FORM2. + + (prog2 (print "The first form") + (print "The second form") + (print "The third form")) + -| "The first form" + -| "The second form" + -| "The third form" + => "The second form" + + +File: lispref.info, Node: Conditionals, Next: Combining Conditions, Prev: Sequencing, Up: Control Structures + +15.2 Conditionals +================= + +Conditional control structures choose among alternatives. XEmacs Lisp +has two conditional forms: `if', which is much the same as in other +languages, and `cond', which is a generalized case statement. + + -- Special Form: if condition then-form else-forms... + `if' chooses between the THEN-FORM and the ELSE-FORMS based on the + value of CONDITION. If the evaluated CONDITION is non-`nil', + THEN-FORM is evaluated and the result returned. Otherwise, the + ELSE-FORMS are evaluated in textual order, and the value of the + last one is returned. (The ELSE part of `if' is an example of an + implicit `progn'. *Note Sequencing::.) + + If CONDITION has the value `nil', and no ELSE-FORMS are given, + `if' returns `nil'. + + `if' is a special form because the branch that is not selected is + never evaluated--it is ignored. Thus, in the example below, + `true' is not printed because `print' is never called. + + (if nil + (print 'true) + 'very-false) + => very-false + + -- Special Form: cond clause... + `cond' chooses among an arbitrary number of alternatives. Each + CLAUSE in the `cond' must be a list. The CAR of this list is the + CONDITION; the remaining elements, if any, the BODY-FORMS. Thus, + a clause looks like this: + + (CONDITION BODY-FORMS...) + + `cond' tries the clauses in textual order, by evaluating the + CONDITION of each clause. If the value of CONDITION is non-`nil', + the clause "succeeds"; then `cond' evaluates its BODY-FORMS, and + the value of the last of BODY-FORMS becomes the value of the + `cond'. The remaining clauses are ignored. + + If the value of CONDITION is `nil', the clause "fails", so the + `cond' moves on to the following clause, trying its CONDITION. + + If every CONDITION evaluates to `nil', so that every clause fails, + `cond' returns `nil'. + + A clause may also look like this: + + (CONDITION) + + Then, if CONDITION is non-`nil' when tested, the value of + CONDITION becomes the value of the `cond' form. + + The following example has four clauses, which test for the cases + where the value of `x' is a number, string, buffer and symbol, + respectively: + + (cond ((numberp x) x) + ((stringp x) x) + ((bufferp x) + (setq temporary-hack x) ; multiple body-forms + (buffer-name x)) ; in one clause + ((symbolp x) (symbol-value x))) + + Often we want to execute the last clause whenever none of the + previous clauses was successful. To do this, we use `t' as the + CONDITION of the last clause, like this: `(t BODY-FORMS)'. The + form `t' evaluates to `t', which is never `nil', so this clause + never fails, provided the `cond' gets to it at all. + + For example, + + (cond ((eq a 'hack) 'foo) + (t "default")) + => "default" + + This expression is a `cond' which returns `foo' if the value of + `a' is 1, and returns the string `"default"' otherwise. + + Any conditional construct can be expressed with `cond' or with `if'. +Therefore, the choice between them is a matter of style. For example: + + (if A B C) + == + (cond (A B) (t C)) + + +File: lispref.info, Node: Combining Conditions, Next: Iteration, Prev: Conditionals, Up: Control Structures + +15.3 Constructs for Combining Conditions +======================================== + +This section describes three constructs that are often used together +with `if' and `cond' to express complicated conditions. The constructs +`and' and `or' can also be used individually as kinds of multiple +conditional constructs. + + -- Function: not condition + This function tests for the falsehood of CONDITION. It returns + `t' if CONDITION is `nil', and `nil' otherwise. The function + `not' is identical to `null', and we recommend using the name + `null' if you are testing for an empty list. + + -- Special Form: and conditions... + The `and' special form tests whether all the CONDITIONS are true. + It works by evaluating the CONDITIONS one by one in the order + written. + + If any of the CONDITIONS evaluates to `nil', then the result of + the `and' must be `nil' regardless of the remaining CONDITIONS; so + `and' returns right away, ignoring the remaining CONDITIONS. + + If all the CONDITIONS turn out non-`nil', then the value of the + last of them becomes the value of the `and' form. + + Here is an example. The first condition returns the integer 1, + which is not `nil'. Similarly, the second condition returns the + integer 2, which is not `nil'. The third condition is `nil', so + the remaining condition is never evaluated. + + (and (print 1) (print 2) nil (print 3)) + -| 1 + -| 2 + => nil + + Here is a more realistic example of using `and': + + (if (and (consp foo) (eq (car foo) 'x)) + (message "foo is a list starting with x")) + + Note that `(car foo)' is not executed if `(consp foo)' returns + `nil', thus avoiding an error. + + `and' can be expressed in terms of either `if' or `cond'. For + example: + + (and ARG1 ARG2 ARG3) + == + (if ARG1 (if ARG2 ARG3)) + == + (cond (ARG1 (cond (ARG2 ARG3)))) + + -- Special Form: or conditions... + The `or' special form tests whether at least one of the CONDITIONS + is true. It works by evaluating all the CONDITIONS one by one in + the order written. + + If any of the CONDITIONS evaluates to a non-`nil' value, then the + result of the `or' must be non-`nil'; so `or' returns right away, + ignoring the remaining CONDITIONS. The value it returns is the + non-`nil' value of the condition just evaluated. + + If all the CONDITIONS turn out `nil', then the `or' expression + returns `nil'. + + For example, this expression tests whether `x' is either 0 or + `nil': + + (or (eq x nil) (eq x 0)) + + Like the `and' construct, `or' can be written in terms of `cond'. + For example: + + (or ARG1 ARG2 ARG3) + == + (cond (ARG1) + (ARG2) + (ARG3)) + + You could almost write `or' in terms of `if', but not quite: + + (if ARG1 ARG1 + (if ARG2 ARG2 + ARG3)) + + This is not completely equivalent because it can evaluate ARG1 or + ARG2 twice. By contrast, `(or ARG1 ARG2 ARG3)' never evaluates + any argument more than once. + + +File: lispref.info, Node: Iteration, Next: Nonlocal Exits, Prev: Combining Conditions, Up: Control Structures + +15.4 Iteration +============== + +Iteration means executing part of a program repetitively. For example, +you might want to repeat some computation once for each element of a +list, or once for each integer from 0 to N. You can do this in XEmacs +Lisp with the special form `while': + + -- Special Form: while condition forms... + `while' first evaluates CONDITION. If the result is non-`nil', it + evaluates FORMS in textual order. Then it reevaluates CONDITION, + and if the result is non-`nil', it evaluates FORMS again. This + process repeats until CONDITION evaluates to `nil'. + + There is no limit on the number of iterations that may occur. The + loop will continue until either CONDITION evaluates to `nil' or + until an error or `throw' jumps out of it (*note Nonlocal Exits::). + + The value of a `while' form is always `nil'. + + (setq num 0) + => 0 + (while (< num 4) + (princ (format "Iteration %d." num)) + (setq num (1+ num))) + -| Iteration 0. + -| Iteration 1. + -| Iteration 2. + -| Iteration 3. + => nil + + If you would like to execute something on each iteration before the + end-test, put it together with the end-test in a `progn' as the + first argument of `while', as shown here: + + (while (progn + (forward-line 1) + (not (looking-at "^$")))) + + This moves forward one line and continues moving by lines until it + reaches an empty. It is unusual in that the `while' has no body, + just the end test (which also does the real work of moving point). + + +File: lispref.info, Node: Nonlocal Exits, Prev: Iteration, Up: Control Structures + +15.5 Nonlocal Exits +=================== + +A "nonlocal exit" is a transfer of control from one point in a program +to another remote point. Nonlocal exits can occur in XEmacs Lisp as a +result of errors; you can also use them under explicit control. +Nonlocal exits unbind all variable bindings made by the constructs being +exited. + +* Menu: + +* Catch and Throw:: Nonlocal exits for the program's own purposes. +* Examples of Catch:: Showing how such nonlocal exits can be written. +* Errors:: How errors are signaled and handled. +* Cleanups:: Arranging to run a cleanup form if an error happens. + + +File: lispref.info, Node: Catch and Throw, Next: Examples of Catch, Up: Nonlocal Exits + +15.5.1 Explicit Nonlocal Exits: `catch' and `throw' +--------------------------------------------------- + +Most control constructs affect only the flow of control within the +construct itself. The function `throw' is the exception to this rule +of normal program execution: it performs a nonlocal exit on request. +(There are other exceptions, but they are for error handling only.) +`throw' is used inside a `catch', and jumps back to that `catch'. For +example: + + (catch 'foo + (progn + ... + (throw 'foo t) + ...)) + +The `throw' transfers control straight back to the corresponding +`catch', which returns immediately. The code following the `throw' is +not executed. The second argument of `throw' is used as the return +value of the `catch'. + + The `throw' and the `catch' are matched through the first argument: +`throw' searches for a `catch' whose first argument is `eq' to the one +specified. Thus, in the above example, the `throw' specifies `foo', +and the `catch' specifies the same symbol, so that `catch' is +applicable. If there is more than one applicable `catch', the +innermost one takes precedence. + + Executing `throw' exits all Lisp constructs up to the matching +`catch', including function calls. When binding constructs such as +`let' or function calls are exited in this way, the bindings are +unbound, just as they are when these constructs exit normally (*note +Local Variables::). Likewise, `throw' restores the buffer and position +saved by `save-excursion' (*note Excursions::), and the narrowing +status saved by `save-restriction' and the window selection saved by +`save-window-excursion' (*note Window Configurations::). It also runs +any cleanups established with the `unwind-protect' special form when it +exits that form (*note Cleanups::). + + The `throw' need not appear lexically within the `catch' that it +jumps to. It can equally well be called from another function called +within the `catch'. As long as the `throw' takes place chronologically +after entry to the `catch', and chronologically before exit from it, it +has access to that `catch'. This is why `throw' can be used in +commands such as `exit-recursive-edit' that throw back to the editor +command loop (*note Recursive Editing::). + + Common Lisp note: Most other versions of Lisp, including Common + Lisp, have several ways of transferring control nonsequentially: + `return', `return-from', and `go', for example. XEmacs Lisp has + only `throw'. + + -- Special Form: catch tag body... + `catch' establishes a return point for the `throw' function. The + return point is distinguished from other such return points by TAG, + which may be any Lisp object. The argument TAG is evaluated + normally before the return point is established. + + With the return point in effect, `catch' evaluates the forms of the + BODY in textual order. If the forms execute normally, without + error or nonlocal exit, the value of the last body form is + returned from the `catch'. + + If a `throw' is done within BODY specifying the same value TAG, + the `catch' exits immediately; the value it returns is whatever + was specified as the second argument of `throw'. + + -- Function: throw tag value + The purpose of `throw' is to return from a return point previously + established with `catch'. The argument TAG is used to choose + among the various existing return points; it must be `eq' to the + value specified in the `catch'. If multiple return points match + TAG, the innermost one is used. + + The argument VALUE is used as the value to return from that + `catch'. + + If no return point is in effect with tag TAG, then a `no-catch' + error is signaled with data `(TAG VALUE)'. + + +File: lispref.info, Node: Examples of Catch, Next: Errors, Prev: Catch and Throw, Up: Nonlocal Exits + +15.5.2 Examples of `catch' and `throw' +-------------------------------------- + +One way to use `catch' and `throw' is to exit from a doubly nested +loop. (In most languages, this would be done with a "go to".) Here we +compute `(foo I J)' for I and J varying from 0 to 9: + + (defun search-foo () + (catch 'loop + (let ((i 0)) + (while (< i 10) + (let ((j 0)) + (while (< j 10) + (if (foo i j) + (throw 'loop (list i j))) + (setq j (1+ j)))) + (setq i (1+ i)))))) + +If `foo' ever returns non-`nil', we stop immediately and return a list +of I and J. If `foo' always returns `nil', the `catch' returns +normally, and the value is `nil', since that is the result of the +`while'. + + Here are two tricky examples, slightly different, showing two return +points at once. First, two return points with the same tag, `hack': + + (defun catch2 (tag) + (catch tag + (throw 'hack 'yes))) + => catch2 + + (catch 'hack + (print (catch2 'hack)) + 'no) + -| yes + => no + +Since both return points have tags that match the `throw', it goes to +the inner one, the one established in `catch2'. Therefore, `catch2' +returns normally with value `yes', and this value is printed. Finally +the second body form in the outer `catch', which is `'no', is evaluated +and returned from the outer `catch'. + + Now let's change the argument given to `catch2': + + (defun catch2 (tag) + (catch tag + (throw 'hack 'yes))) + => catch2 + + (catch 'hack + (print (catch2 'quux)) + 'no) + => yes + +We still have two return points, but this time only the outer one has +the tag `hack'; the inner one has the tag `quux' instead. Therefore, +`throw' makes the outer `catch' return the value `yes'. The function +`print' is never called, and the body-form `'no' is never evaluated. + + +File: lispref.info, Node: Errors, Next: Cleanups, Prev: Examples of Catch, Up: Nonlocal Exits + +15.5.3 Errors +------------- + +When XEmacs Lisp attempts to evaluate a form that, for some reason, +cannot be evaluated, it "signals" an "error". + + When an error is signaled, XEmacs's default reaction is to print an +error message and terminate execution of the current command. This is +the right thing to do in most cases, such as if you type `C-f' at the +end of the buffer. + + In complicated programs, simple termination may not be what you want. +For example, the program may have made temporary changes in data +structures, or created temporary buffers that should be deleted before +the program is finished. In such cases, you would use `unwind-protect' +to establish "cleanup expressions" to be evaluated in case of error. +(*Note Cleanups::.) Occasionally, you may wish the program to continue +execution despite an error in a subroutine. In these cases, you would +use `condition-case' to establish "error handlers" to recover control +in case of error. + + Resist the temptation to use error handling to transfer control from +one part of the program to another; use `catch' and `throw' instead. +*Note Catch and Throw::. + +* Menu: + +* Signaling Errors:: How to report an error. +* Processing of Errors:: What XEmacs does when you report an error. +* Handling Errors:: How you can trap errors and continue execution. +* Error Symbols:: How errors are classified for trapping them. + + +File: lispref.info, Node: Signaling Errors, Next: Processing of Errors, Up: Errors + +15.5.3.1 How to Signal an Error +............................... + +Most errors are signaled "automatically" within Lisp primitives which +you call for other purposes, such as if you try to take the CAR of an +integer or move forward a character at the end of the buffer; you can +also signal errors explicitly with the functions `error', `signal', and +others. + + Quitting, which happens when the user types `C-g', is not considered +an error, but it is handled almost like an error. *Note Quitting::. + + XEmacs has a rich hierarchy of error symbols predefined via +`deferror'. + + error + syntax-error + invalid-read-syntax + list-formation-error + malformed-list + malformed-property-list + circular-list + circular-property-list + + invalid-argument + wrong-type-argument + args-out-of-range + wrong-number-of-arguments + invalid-function + no-catch + + invalid-state + void-function + cyclic-function-indirection + void-variable + cyclic-variable-indirection + + invalid-operation + invalid-change + setting-constant + editing-error + beginning-of-buffer + end-of-buffer + buffer-read-only + io-error + end-of-file + arith-error + range-error + domain-error + singularity-error + overflow-error + underflow-error + + The five most common errors you will probably use or base your new +errors off of are `syntax-error', `invalid-argument', `invalid-state', +`invalid-operation', and `invalid-change'. Note the semantic +differences: + + * `syntax-error' is for errors in complex structures: parsed strings, + lists, and the like. + + * `invalid-argument' is for errors in a simple value. Typically, the + entire value, not just one part of it, is wrong. + + * `invalid-state' means that some settings have been changed in such + a way that their current state is unallowable. More and more, + code is being written more carefully, and catches the error when + the settings are being changed, rather than afterwards. This + leads us to the next error: + + * `invalid-change' means that an attempt is being made to change some + settings into an invalid state. `invalid-change' is a type of + `invalid-operation'. + + * `invalid-operation' refers to all cases where code is trying to do + something that's disallowed. This includes file errors, buffer + errors (e.g. running off the end of a buffer), `invalid-change' as + just mentioned, and arithmetic errors. + + -- Function: error datum &rest args + This function signals a non-continuable error. + + DATUM should normally be an error symbol, i.e. a symbol defined + using `define-error'. ARGS will be made into a list, and DATUM + and ARGS passed as the two arguments to `signal', the most basic + error handling function. + + This error is not continuable: you cannot continue execution after + the error using the debugger `r' command. See also `cerror'. + + The correct semantics of ARGS varies from error to error, but for + most errors that need to be generated in Lisp code, the first + argument should be a string describing the *context* of the error + (i.e. the exact operation being performed and what went wrong), + and the remaining arguments or \"frobs\" (most often, there is + one) specify the offending object(s) and/or provide additional + details such as the exact error when a file error occurred, e.g.: + + * the buffer in which an editing error occurred. + + * an invalid value that was encountered. (In such cases, the + string should describe the purpose or \"semantics\" of the + value [e.g. if the value is an argument to a function, the + name of the argument; if the value is the value corresponding + to a keyword, the name of the keyword; if the value is + supposed to be a list length, say this and say what the + purpose of the list is; etc.] as well as specifying why the + value is invalid, if that's not self-evident.) + + * the file in which an error occurred. (In such cases, there + should be a second frob, probably a string, specifying the + exact error that occurred. This does not occur in the string + that precedes the first frob, because that frob describes the + exact operation that was happening. + + For historical compatibility, DATUM can also be a string. In this + case, DATUM and ARGS are passed together as the arguments to + `format', and then an error is signalled using the error symbol + `error' and formatted string. Although this usage of `error' is + very common, it is deprecated because it totally defeats the + purpose of having structured errors. There is now a rich set of + defined errors to use. + + See also `cerror', `signal', and `signal-error'." + + These examples show typical uses of `error': + + (error 'syntax-error + "Dialog descriptor must supply at least one button" + descriptor) + + (error "You have committed an error. + Try something else.") + error--> You have committed an error. + Try something else. + + (error "You have committed %d errors." 10) + error--> You have committed 10 errors. + + If you want to use your own string as an error message verbatim, + don't just write `(error STRING)'. If STRING contains `%', it + will be interpreted as a format specifier, with undesirable + results. Instead, use `(error "%s" STRING)'. + + -- Function: cerror datum &rest args + This function behaves like `error', except that the error it + signals is continuable. That means that debugger commands `c' and + `r' can resume execution. + + -- Function: signal error-symbol data + This function signals a continuable error named by ERROR-SYMBOL. + The argument DATA is a list of additional Lisp objects relevant to + the circumstances of the error. + + The argument ERROR-SYMBOL must be an "error symbol"--a symbol + bearing a property `error-conditions' whose value is a list of + condition names. This is how XEmacs Lisp classifies different + sorts of errors. + + The number and significance of the objects in DATA depends on + ERROR-SYMBOL. For example, with a `wrong-type-argument' error, + there are two objects in the list: a predicate that describes the + type that was expected, and the object that failed to fit that + type. *Note Error Symbols::, for a description of error symbols. + + Both ERROR-SYMBOL and DATA are available to any error handlers + that handle the error: `condition-case' binds a local variable to + a list of the form `(ERROR-SYMBOL . DATA)' (*note Handling + Errors::). If the error is not handled, these two values are used + in printing the error message. + + The function `signal' can return, if the debugger is invoked and + the user invokes the "return from signal" option. If you want the + error not to be continuable, use `signal-error' instead. Note that + in FSF Emacs `signal' never returns. + + (signal 'wrong-number-of-arguments '(x y)) + error--> Wrong number of arguments: x, y + + (signal 'no-such-error '("My unknown error condition")) + error--> Peculiar error (no-such-error "My unknown error condition") + + -- Function: signal-error error-symbol data + This function behaves like `signal', except that the error it + signals is not continuable. + + -- Macro: check-argument-type predicate argument + This macro checks that ARGUMENT satisfies PREDICATE. If that is + not the case, it signals a continuable `wrong-type-argument' error + until the returned value satisfies PREDICATE, and assigns the + returned value to ARGUMENT. In other words, execution of the + program will not continue until PREDICATE is met. + + ARGUMENT is not evaluated, and should be a symbol. PREDICATE is + evaluated, and should name a function. + + As shown in the following example, `check-argument-type' is useful + in low-level code that attempts to ensure the sanity of its data + before proceeding. + + (defun cache-object-internal (object wlist) + ;; Before doing anything, make sure that WLIST is indeed + ;; a weak list, which is what we expect. + (check-argument-type 'weak-list-p wlist) + ...) + + +File: lispref.info, Node: Processing of Errors, Next: Handling Errors, Prev: Signaling Errors, Up: Errors + +15.5.3.2 How XEmacs Processes Errors +.................................... + +When an error is signaled, `signal' searches for an active "handler" +for the error. A handler is a sequence of Lisp expressions designated +to be executed if an error happens in part of the Lisp program. If the +error has an applicable handler, the handler is executed, and control +resumes following the handler. The handler executes in the environment +of the `condition-case' that established it; all functions called +within that `condition-case' have already been exited, and the handler +cannot return to them. + + If there is no applicable handler for the error, the current command +is terminated and control returns to the editor command loop, because +the command loop has an implicit handler for all kinds of errors. The +command loop's handler uses the error symbol and associated data to +print an error message. + + Errors in command loop are processed using the `command-error' +function, which takes care of some necessary cleanup, and prints a +formatted error message to the echo area. The functions that do the +formatting are explained below. + + -- Function: display-error error-object stream + This function displays ERROR-OBJECT on STREAM. ERROR-OBJECT is a + cons of error type, a symbol, and error arguments, a list. If the + error type symbol of one of its error condition superclasses has a + `display-error' property, that function is invoked for printing + the actual error message. Otherwise, the error is printed as + `Error: arg1, arg2, ...'. + + -- Function: error-message-string error-object + This function converts ERROR-OBJECT to an error message string, + and returns it. The message is equivalent to the one that would be + printed by `display-error', except that it is conveniently returned + in string form. + + An error that has no explicit handler may call the Lisp debugger. +The debugger is enabled if the variable `debug-on-error' (*note Error +Debugging::) is non-`nil'. Unlike error handlers, the debugger runs in +the environment of the error, so that you can examine values of +variables precisely as they were at the time of the error. + + +File: lispref.info, Node: Handling Errors, Next: Error Symbols, Prev: Processing of Errors, Up: Errors + +15.5.3.3 Writing Code to Handle Errors +...................................... + +The usual effect of signaling an error is to terminate the command that +is running and return immediately to the XEmacs editor command loop. +You can arrange to trap errors occurring in a part of your program by +establishing an error handler, with the special form `condition-case'. +A simple example looks like this: + + (condition-case nil + (delete-file filename) + (error nil)) + +This deletes the file named FILENAME, catching any error and returning +`nil' if an error occurs. + + The second argument of `condition-case' is called the "protected +form". (In the example above, the protected form is a call to +`delete-file'.) The error handlers go into effect when this form +begins execution and are deactivated when this form returns. They +remain in effect for all the intervening time. In particular, they are +in effect during the execution of functions called by this form, in +their subroutines, and so on. This is a good thing, since, strictly +speaking, errors can be signaled only by Lisp primitives (including +`signal' and `error') called by the protected form, not by the +protected form itself. + + The arguments after the protected form are handlers. Each handler +lists one or more "condition names" (which are symbols) to specify +which errors it will handle. The error symbol specified when an error +is signaled also defines a list of condition names. A handler applies +to an error if they have any condition names in common. In the example +above, there is one handler, and it specifies one condition name, +`error', which covers all errors. + + The search for an applicable handler checks all the established +handlers starting with the most recently established one. Thus, if two +nested `condition-case' forms offer to handle the same error, the inner +of the two will actually handle it. + + When an error is handled, control returns to the handler. Before +this happens, XEmacs unbinds all variable bindings made by binding +constructs that are being exited and executes the cleanups of all +`unwind-protect' forms that are exited. Once control arrives at the +handler, the body of the handler is executed. + + After execution of the handler body, execution continues by returning +from the `condition-case' form. Because the protected form is exited +completely before execution of the handler, the handler cannot resume +execution at the point of the error, nor can it examine variable +bindings that were made within the protected form. All it can do is +clean up and proceed. + + `condition-case' is often used to trap errors that are predictable, +such as failure to open a file in a call to `insert-file-contents'. It +is also used to trap errors that are totally unpredictable, such as +when the program evaluates an expression read from the user. + + Even when an error is handled, the debugger may still be called if +the variable `debug-on-signal' (*note Error Debugging::) is non-`nil'. +Note that this may yield unpredictable results with code that traps +expected errors as normal part of its operation. Do not set +`debug-on-signal' unless you know what you are doing. + + Error signaling and handling have some resemblance to `throw' and +`catch', but they are entirely separate facilities. An error cannot be +caught by a `catch', and a `throw' cannot be handled by an error +handler (though using `throw' when there is no suitable `catch' signals +an error that can be handled). + + -- Special Form: condition-case var protected-form handlers... + This special form establishes the error handlers HANDLERS around + the execution of PROTECTED-FORM. If PROTECTED-FORM executes + without error, the value it returns becomes the value of the + `condition-case' form; in this case, the `condition-case' has no + effect. The `condition-case' form makes a difference when an + error occurs during PROTECTED-FORM. + + Each of the HANDLERS is a list of the form `(CONDITIONS BODY...)'. + Here CONDITIONS is an error condition name to be handled, or a + list of condition names; BODY is one or more Lisp expressions to + be executed when this handler handles an error. Here are examples + of handlers: + + (error nil) + + (arith-error (message "Division by zero")) + + ((arith-error file-error) + (message + "Either division by zero or failure to open a file")) + + Each error that occurs has an "error symbol" that describes what + kind of error it is. The `error-conditions' property of this + symbol is a list of condition names (*note Error Symbols::). Emacs + searches all the active `condition-case' forms for a handler that + specifies one or more of these condition names; the innermost + matching `condition-case' handles the error. Within this + `condition-case', the first applicable handler handles the error. + + After executing the body of the handler, the `condition-case' + returns normally, using the value of the last form in the handler + body as the overall value. + + The argument VAR is a variable. `condition-case' does not bind + this variable when executing the PROTECTED-FORM, only when it + handles an error. At that time, it binds VAR locally to a list of + the form `(ERROR-SYMBOL . DATA)', giving the particulars of the + error. The handler can refer to this list to decide what to do. + For example, if the error is for failure opening a file, the file + name is the second element of DATA--the third element of VAR. + + If VAR is `nil', that means no variable is bound. Then the error + symbol and associated data are not available to the handler. + + Here is an example of using `condition-case' to handle the error +that results from dividing by zero. The handler prints out a warning +message and returns a very large number. + + (defun safe-divide (dividend divisor) + (condition-case err + ;; Protected form. + (/ dividend divisor) + ;; The handler. + (arith-error ; Condition. + (princ (format "Arithmetic error: %s" err)) + 1000000))) + => safe-divide + + (safe-divide 5 0) + -| Arithmetic error: (arith-error) + => 1000000 + +The handler specifies condition name `arith-error' so that it will +handle only division-by-zero errors. Other kinds of errors will not be +handled, at least not by this `condition-case'. Thus, + + (safe-divide nil 3) + error--> Wrong type argument: integer-or-marker-p, nil + + Here is a `condition-case' that catches all kinds of errors, +including those signaled with `error': + + (setq baz 34) + => 34 + + (condition-case err + (if (eq baz 35) + t + ;; This is a call to the function `error'. + (error "Rats! The variable %s was %s, not 35" 'baz baz)) + ;; This is the handler; it is not a form. + (error (princ (format "The error was: %s" err)) + 2)) + -| The error was: (error "Rats! The variable baz was 34, not 35") + => 2 + + +File: lispref.info, Node: Error Symbols, Prev: Handling Errors, Up: Errors + +15.5.3.4 Error Symbols and Condition Names +.......................................... + +When you signal an error, you specify an "error symbol" to specify the +kind of error you have in mind. Each error has one and only one error +symbol to categorize it. This is the finest classification of errors +defined by the XEmacs Lisp language. + + These narrow classifications are grouped into a hierarchy of wider +classes called "error conditions", identified by "condition names". +The narrowest such classes belong to the error symbols themselves: each +error symbol is also a condition name. There are also condition names +for more extensive classes, up to the condition name `error' which +takes in all kinds of errors. Thus, each error has one or more +condition names: `error', the error symbol if that is distinct from +`error', and perhaps some intermediate classifications. + + In other words, each error condition "inherits" from another error +condition, with `error' sitting at the top of the inheritance hierarchy. + + -- Function: define-error error-symbol error-message &optional + inherits-from + This function defines a new error, denoted by ERROR-SYMBOL. + ERROR-MESSAGE is an informative message explaining the error, and + will be printed out when an unhandled error occurs. ERROR-SYMBOL + is a sub-error of INHERITS-FROM (which defaults to `error'). + + `define-error' internally works by putting on ERROR-SYMBOL an + `error-message' property whose value is ERROR-MESSAGE, and an + `error-conditions' property that is a list of ERROR-SYMBOL + followed by each of its super-errors, up to and including `error'. + You will sometimes see code that sets this up directly rather than + calling `define-error', but you should _not_ do this yourself, + unless you wish to maintain compatibility with FSF Emacs, which + does not provide `define-error'. + + Here is how we define a new error symbol, `new-error', that belongs +to a range of errors called `my-own-errors': + + (define-error 'my-own-errors "A whole range of errors" 'error) + (define-error 'new-error "A new error" 'my-own-errors) + +`new-error' has three condition names: `new-error', the narrowest +classification; `my-own-errors', which we imagine is a wider +classification; and `error', which is the widest of all. + + Note that it is not legal to try to define an error unless its +super-error is also defined. For instance, attempting to define +`new-error' before `my-own-errors' are defined will signal an error. + + The error string should start with a capital letter but it should +not end with a period. This is for consistency with the rest of Emacs. + + Naturally, XEmacs will never signal `new-error' on its own; only an +explicit call to `signal' (*note Signaling Errors::) in your code can +do this: + + (signal 'new-error '(x y)) + error--> A new error: x, y + + This error can be handled through any of the three condition names. +This example handles `new-error' and any other errors in the class +`my-own-errors': + + (condition-case foo + (bar nil t) + (my-own-errors nil)) + + The significant way that errors are classified is by their condition +names--the names used to match errors with handlers. An error symbol +serves only as a convenient way to specify the intended error message +and list of condition names. It would be cumbersome to give `signal' a +list of condition names rather than one error symbol. + + By contrast, using only error symbols without condition names would +seriously decrease the power of `condition-case'. Condition names make +it possible to categorize errors at various levels of generality when +you write an error handler. Using error symbols alone would eliminate +all but the narrowest level of classification. + + *Note Standard Errors::, for a list of all the standard error symbols +and their conditions. + + +File: lispref.info, Node: Cleanups, Prev: Errors, Up: Nonlocal Exits + +15.5.4 Cleaning Up from Nonlocal Exits +-------------------------------------- + +The `unwind-protect' construct is essential whenever you temporarily +put a data structure in an inconsistent state; it permits you to ensure +the data are consistent in the event of an error or throw. + + -- Special Form: unwind-protect body cleanup-forms... + `unwind-protect' executes the BODY with a guarantee that the + CLEANUP-FORMS will be evaluated if control leaves BODY, no matter + how that happens. The BODY may complete normally, or execute a + `throw' out of the `unwind-protect', or cause an error; in all + cases, the CLEANUP-FORMS will be evaluated. + + If the BODY forms finish normally, `unwind-protect' returns the + value of the last BODY form, after it evaluates the CLEANUP-FORMS. + If the BODY forms do not finish, `unwind-protect' does not return + any value in the normal sense. + + Only the BODY is actually protected by the `unwind-protect'. If + any of the CLEANUP-FORMS themselves exits nonlocally (e.g., via a + `throw' or an error), `unwind-protect' is _not_ guaranteed to + evaluate the rest of them. If the failure of one of the + CLEANUP-FORMS has the potential to cause trouble, then protect it + with another `unwind-protect' around that form. + + The number of currently active `unwind-protect' forms counts, + together with the number of local variable bindings, against the + limit `max-specpdl-size' (*note Local Variables::). + + For example, here we make an invisible buffer for temporary use, and +make sure to kill it before finishing: + + (save-excursion + (let ((buffer (get-buffer-create " *temp*"))) + (set-buffer buffer) + (unwind-protect + BODY + (kill-buffer buffer)))) + +You might think that we could just as well write `(kill-buffer +(current-buffer))' and dispense with the variable `buffer'. However, +the way shown above is safer, if BODY happens to get an error after +switching to a different buffer! (Alternatively, you could write +another `save-excursion' around the body, to ensure that the temporary +buffer becomes current in time to kill it.) + + Here is an actual example taken from the file `ftp.el'. It creates +a process (*note Processes::) to try to establish a connection to a +remote machine. As the function `ftp-login' is highly susceptible to +numerous problems that the writer of the function cannot anticipate, it +is protected with a form that guarantees deletion of the process in the +event of failure. Otherwise, XEmacs might fill up with useless +subprocesses. + + (let ((win nil)) + (unwind-protect + (progn + (setq process (ftp-setup-buffer host file)) + (if (setq win (ftp-login process host user password)) + (message "Logged in") + (error "Ftp login failed"))) + (or win (and process (delete-process process))))) + + This example actually has a small bug: if the user types `C-g' to +quit, and the quit happens immediately after the function +`ftp-setup-buffer' returns but before the variable `process' is set, +the process will not be killed. There is no easy way to fix this bug, +but at least it is very unlikely. + + Here is another example which uses `unwind-protect' to make sure to +kill a temporary buffer. In this example, the value returned by +`unwind-protect' is used. + + (defun shell-command-string (cmd) + "Return the output of the shell command CMD, as a string." + (save-excursion + (set-buffer (generate-new-buffer " OS*cmd")) + (shell-command cmd t) + (unwind-protect + (buffer-string) + (kill-buffer (current-buffer))))) + + +File: lispref.info, Node: Variables, Next: Functions and Commands, Prev: Control Structures, Up: Top + +16 Variables +************ + +A "variable" is a name used in a program to stand for a value. Nearly +all programming languages have variables of some sort. In the text of +a Lisp program, variables are written using the syntax for symbols. + + In Lisp, unlike most programming languages, programs are represented +primarily as Lisp objects and only secondarily as text. The Lisp +objects used for variables are symbols: the symbol name is the variable +name, and the variable's value is stored in the value cell of the +symbol. The use of a symbol as a variable is independent of its use as +a function name. *Note Symbol Components::. + + The Lisp objects that constitute a Lisp program determine the textual +form of the program--it is simply the read syntax for those Lisp +objects. This is why, for example, a variable in a textual Lisp program +is written using the read syntax for the symbol that represents the +variable. + +* Menu: + +* Global Variables:: Variable values that exist permanently, everywhere. +* Constant Variables:: Certain "variables" have values that never change. +* Local Variables:: Variable values that exist only temporarily. +* Void Variables:: Symbols that lack values. +* Defining Variables:: A definition says a symbol is used as a variable. +* Accessing Variables:: Examining values of variables whose names + are known only at run time. +* Setting Variables:: Storing new values in variables. +* Variable Scoping:: How Lisp chooses among local and global values. +* Buffer-Local Variables:: Variable values in effect only in one buffer. +* Variable Aliases:: Making one variable point to another. + + +File: lispref.info, Node: Global Variables, Next: Constant Variables, Up: Variables + +16.1 Global Variables +===================== + +The simplest way to use a variable is "globally". This means that the +variable has just one value at a time, and this value is in effect (at +least for the moment) throughout the Lisp system. The value remains in +effect until you specify a new one. When a new value replaces the old +one, no trace of the old value remains in the variable. + + You specify a value for a symbol with `setq'. For example, + + (setq x '(a b)) + +gives the variable `x' the value `(a b)'. Note that `setq' does not +evaluate its first argument, the name of the variable, but it does +evaluate the second argument, the new value. + + Once the variable has a value, you can refer to it by using the +symbol by itself as an expression. Thus, + + x => (a b) + +assuming the `setq' form shown above has already been executed. + + If you do another `setq', the new value replaces the old one: + + x + => (a b) + (setq x 4) + => 4 + x + => 4 + + +File: lispref.info, Node: Constant Variables, Next: Local Variables, Prev: Global Variables, Up: Variables + +16.2 Variables That Never Change +================================ + +In XEmacs Lisp, some symbols always evaluate to themselves: the two +special symbols `nil' and `t', as well as "keyword symbols", that is, +symbols whose name begins with the character ``:''. These symbols +cannot be rebound, nor can their value cells be changed. An attempt to +change the value of `nil' or `t' signals a `setting-constant' error. + + nil == 'nil + => nil + (setq nil 500) + error--> Attempt to set constant symbol: nil + + +File: lispref.info, Node: Local Variables, Next: Void Variables, Prev: Constant Variables, Up: Variables + +16.3 Local Variables +==================== + +Global variables have values that last until explicitly superseded with +new values. Sometimes it is useful to create variable values that +exist temporarily--only while within a certain part of the program. +These values are called "local", and the variables so used are called +"local variables". + + For example, when a function is called, its argument variables +receive new local values that last until the function exits. The `let' +special form explicitly establishes new local values for specified +variables; these last until exit from the `let' form. + + Establishing a local value saves away the previous value (or lack of +one) of the variable. When the life span of the local value is over, +the previous value is restored. In the mean time, we say that the +previous value is "shadowed" and "not visible". Both global and local +values may be shadowed (*note Scope::). + + If you set a variable (such as with `setq') while it is local, this +replaces the local value; it does not alter the global value, or +previous local values that are shadowed. To model this behavior, we +speak of a "local binding" of the variable as well as a local value. + + The local binding is a conceptual place that holds a local value. +Entry to a function, or a special form such as `let', creates the local +binding; exit from the function or from the `let' removes the local +binding. As long as the local binding lasts, the variable's value is +stored within it. Use of `setq' or `set' while there is a local +binding stores a different value into the local binding; it does not +create a new binding. + + We also speak of the "global binding", which is where (conceptually) +the global value is kept. + + A variable can have more than one local binding at a time (for +example, if there are nested `let' forms that bind it). In such a +case, the most recently created local binding that still exists is the +"current binding" of the variable. (This is called "dynamic scoping"; +see *Note Variable Scoping::.) If there are no local bindings, the +variable's global binding is its current binding. We also call the +current binding the "most-local existing binding", for emphasis. +Ordinary evaluation of a symbol always returns the value of its current +binding. + + The special forms `let' and `let*' exist to create local bindings. + + -- Special Form: let (bindings...) forms... + This special form binds variables according to BINDINGS and then + evaluates all of the FORMS in textual order. The `let'-form + returns the value of the last form in FORMS. + + Each of the BINDINGS is either (i) a symbol, in which case that + symbol is bound to `nil'; or (ii) a list of the form `(SYMBOL + VALUE-FORM)', in which case SYMBOL is bound to the result of + evaluating VALUE-FORM. If VALUE-FORM is omitted, `nil' is used. + + All of the VALUE-FORMs in BINDINGS are evaluated in the order they + appear and _before_ any of the symbols are bound. Here is an + example of this: `Z' is bound to the old value of `Y', which is 2, + not the new value, 1. + + (setq Y 2) + => 2 + (let ((Y 1) + (Z Y)) + (list Y Z)) + => (1 2) + + -- Special Form: let* (bindings...) forms... + This special form is like `let', but it binds each variable right + after computing its local value, before computing the local value + for the next variable. Therefore, an expression in BINDINGS can + reasonably refer to the preceding symbols bound in this `let*' + form. Compare the following example with the example above for + `let'. + + (setq Y 2) + => 2 + (let* ((Y 1) + (Z Y)) ; Use the just-established value of `Y'. + (list Y Z)) + => (1 1) + + Here is a complete list of the other facilities that create local +bindings: + + * Function calls (*note Functions and Commands::). + + * Macro calls (*note Macros::). + + * `condition-case' (*note Errors::). + + Variables can also have buffer-local bindings (*note Buffer-Local +Variables::). These kinds of bindings work somewhat like ordinary local +bindings, but they are localized depending on "where" you are in Emacs, +rather than localized in time. + + -- Variable: max-specpdl-size + This variable defines the limit on the total number of local + variable bindings and `unwind-protect' cleanups (*note Nonlocal + Exits::) that are allowed before signaling an error (with data + `"Variable binding depth exceeds max-specpdl-size"'). + + This limit, with the associated error when it is exceeded, is one + way that Lisp avoids infinite recursion on an ill-defined function. + + The default value is 3000. + + `max-lisp-eval-depth' provides another limit on depth of nesting. + *Note Eval::. + + +File: lispref.info, Node: Void Variables, Next: Defining Variables, Prev: Local Variables, Up: Variables + +16.4 When a Variable is "Void" +============================== + +If you have never given a symbol any value as a global variable, we say +that that symbol's global value is "void". In other words, the +symbol's value cell does not have any Lisp object in it. If you try to +evaluate the symbol, you get a `void-variable' error rather than a +value. + + Note that a value of `nil' is not the same as void. The symbol +`nil' is a Lisp object and can be the value of a variable just as any +other object can be; but it is _a value_. A void variable does not +have any value. + + After you have given a variable a value, you can make it void once +more using `makunbound'. + + -- Function: makunbound symbol + This function makes the current binding of SYMBOL void. + Subsequent attempts to use this symbol's value as a variable will + signal the error `void-variable', unless or until you set it again. + + `makunbound' returns SYMBOL. + + (makunbound 'x) ; Make the global value + ; of `x' void. + => x + x + error--> Symbol's value as variable is void: x + + If SYMBOL is locally bound, `makunbound' affects the most local + existing binding. This is the only way a symbol can have a void + local binding, since all the constructs that create local bindings + create them with values. In this case, the voidness lasts at most + as long as the binding does; when the binding is removed due to + exit from the construct that made it, the previous or global + binding is reexposed as usual, and the variable is no longer void + unless the newly reexposed binding was void all along. + + (setq x 1) ; Put a value in the global binding. + => 1 + (let ((x 2)) ; Locally bind it. + (makunbound 'x) ; Void the local binding. + x) + error--> Symbol's value as variable is void: x + x ; The global binding is unchanged. + => 1 + + (let ((x 2)) ; Locally bind it. + (let ((x 3)) ; And again. + (makunbound 'x) ; Void the innermost-local binding. + x)) ; And refer: it's void. + error--> Symbol's value as variable is void: x + + (let ((x 2)) + (let ((x 3)) + (makunbound 'x)) ; Void inner binding, then remove it. + x) ; Now outer `let' binding is visible. + => 2 + + A variable that has been made void with `makunbound' is +indistinguishable from one that has never received a value and has +always been void. + + You can use the function `boundp' to test whether a variable is +currently void. + + -- Function: boundp variable + `boundp' returns `t' if VARIABLE (a symbol) is not void; more + precisely, if its current binding is not void. It returns `nil' + otherwise. + + (boundp 'abracadabra) ; Starts out void. + => nil + (let ((abracadabra 5)) ; Locally bind it. + (boundp 'abracadabra)) + => t + (boundp 'abracadabra) ; Still globally void. + => nil + (setq abracadabra 5) ; Make it globally nonvoid. + => 5 + (boundp 'abracadabra) + => t + + +File: lispref.info, Node: Defining Variables, Next: Accessing Variables, Prev: Void Variables, Up: Variables + +16.5 Defining Global Variables +============================== + +You may announce your intention to use a symbol as a global variable +with a "variable definition": a special form, either `defconst' or +`defvar'. + + In XEmacs Lisp, definitions serve three purposes. First, they inform +people who read the code that certain symbols are _intended_ to be used +a certain way (as variables). Second, they inform the Lisp system of +these things, supplying a value and documentation. Third, they provide +information to utilities such as `etags' and `make-docfile', which +create data bases of the functions and variables in a program. + + The difference between `defconst' and `defvar' is primarily a matter +of intent, serving to inform human readers of whether programs will +change the variable. XEmacs Lisp does not restrict the ways in which a +variable can be used based on `defconst' or `defvar' declarations. +However, it does make a difference for initialization: `defconst' +unconditionally initializes the variable, while `defvar' initializes it +only if it is void. + + One would expect user option variables to be defined with +`defconst', since programs do not change them. Unfortunately, this has +bad results if the definition is in a library that is not preloaded: +`defconst' would override any prior value when the library is loaded. +Users would like to be able to set user options in their init files, +and override the default values given in the definitions. For this +reason, user options must be defined with `defvar'. + + -- Special Form: defvar symbol [value [doc-string]] + This special form defines SYMBOL as a value and initializes it. + The definition informs a person reading your code that SYMBOL is + used as a variable that programs are likely to set or change. It + is also used for all user option variables except in the preloaded + parts of XEmacs. Note that SYMBOL is not evaluated; the symbol to + be defined must appear explicitly in the `defvar'. + + If SYMBOL already has a value (i.e., it is not void), VALUE is not + even evaluated, and SYMBOL's value remains unchanged. If SYMBOL + is void and VALUE is specified, `defvar' evaluates it and sets + SYMBOL to the result. (If VALUE is omitted, the value of SYMBOL + is not changed in any case.) + + When you evaluate a top-level `defvar' form with `C-M-x' in Emacs + Lisp mode (`eval-defun'), a special feature of `eval-defun' + evaluates it as a `defconst'. The purpose of this is to make sure + the variable's value is reinitialized, when you ask for it + specifically. + + If SYMBOL has a buffer-local binding in the current buffer, + `defvar' sets the default value, not the local value. *Note + Buffer-Local Variables::. + + If the DOC-STRING argument appears, it specifies the documentation + for the variable. (This opportunity to specify documentation is + one of the main benefits of defining the variable.) The + documentation is stored in the symbol's `variable-documentation' + property. The XEmacs help functions (*note Documentation::) look + for this property. + + If the first character of DOC-STRING is `*', it means that this + variable is considered a user option. This lets users set the + variable conveniently using the commands `set-variable' and + `edit-options'. + + For example, this form defines `foo' but does not set its value: + + (defvar foo) + => foo + + The following example sets the value of `bar' to `23', and gives + it a documentation string: + + (defvar bar 23 + "The normal weight of a bar.") + => bar + + The following form changes the documentation string for `bar', + making it a user option, but does not change the value, since `bar' + already has a value. (The addition `(1+ 23)' is not even + performed.) + + (defvar bar (1+ 23) + "*The normal weight of a bar.") + => bar + bar + => 23 + + Here is an equivalent expression for the `defvar' special form: + + (defvar SYMBOL VALUE DOC-STRING) + == + (progn + (if (not (boundp 'SYMBOL)) + (setq SYMBOL VALUE)) + (put 'SYMBOL 'variable-documentation 'DOC-STRING) + 'SYMBOL) + + The `defvar' form returns SYMBOL, but it is normally used at top + level in a file where its value does not matter. + + -- Special Form: defconst symbol [value [doc-string]] + This special form defines SYMBOL as a value and initializes it. + It informs a person reading your code that SYMBOL has a global + value, established here, that will not normally be changed or + locally bound by the execution of the program. The user, however, + may be welcome to change it. Note that SYMBOL is not evaluated; + the symbol to be defined must appear explicitly in the `defconst'. + + `defconst' always evaluates VALUE and sets the global value of + SYMBOL to the result, provided VALUE is given. If SYMBOL has a + buffer-local binding in the current buffer, `defconst' sets the + default value, not the local value. + + *Please note:* Don't use `defconst' for user option variables in + libraries that are not standardly preloaded. The user should be + able to specify a value for such a variable in the `.emacs' file, + so that it will be in effect if and when the library is loaded + later. + + Here, `pi' is a constant that presumably ought not to be changed + by anyone (attempts by the Indiana State Legislature + notwithstanding). As the second form illustrates, however, this + is only advisory. + + (defconst pi 3.1415 "Pi to five places.") + => pi + (setq pi 3) + => pi + pi + => 3 + + -- Function: user-variable-p variable + This function returns `t' if VARIABLE is a user option--a variable + intended to be set by the user for customization--and `nil' + otherwise. (Variables other than user options exist for the + internal purposes of Lisp programs, and users need not know about + them.) + + User option variables are distinguished from other variables by the + first character of the `variable-documentation' property. If the + property exists and is a string, and its first character is `*', + then the variable is a user option. + + If a user option variable has a `variable-interactive' property, the +`set-variable' command uses that value to control reading the new value +for the variable. The property's value is used as if it were the +argument to `interactive'. + + *Warning:* If the `defconst' and `defvar' special forms are used +while the variable has a local binding, they set the local binding's +value; the global binding is not changed. This is not what we really +want. To prevent it, use these special forms at top level in a file, +where normally no local binding is in effect, and make sure to load the +file before making a local binding for the variable. + + +File: lispref.info, Node: Accessing Variables, Next: Setting Variables, Prev: Defining Variables, Up: Variables + +16.6 Accessing Variable Values +============================== + +The usual way to reference a variable is to write the symbol which +names it (*note Symbol Forms::). This requires you to specify the +variable name when you write the program. Usually that is exactly what +you want to do. Occasionally you need to choose at run time which +variable to reference; then you can use `symbol-value'. + + -- Function: symbol-value symbol + This function returns the value of SYMBOL. This is the value in + the innermost local binding of the symbol, or its global value if + it has no local bindings. + + (setq abracadabra 5) + => 5 + (setq foo 9) + => 9 + + ;; Here the symbol `abracadabra' + ;; is the symbol whose value is examined. + (let ((abracadabra 'foo)) + (symbol-value 'abracadabra)) + => foo + + ;; Here the value of `abracadabra', + ;; which is `foo', + ;; is the symbol whose value is examined. + (let ((abracadabra 'foo)) + (symbol-value abracadabra)) + => 9 + + (symbol-value 'abracadabra) + => 5 + + A `void-variable' error is signaled if SYMBOL has neither a local + binding nor a global value. + + +File: lispref.info, Node: Setting Variables, Next: Variable Scoping, Prev: Accessing Variables, Up: Variables + +16.7 How to Alter a Variable Value +================================== + +The usual way to change the value of a variable is with the special +form `setq'. When you need to compute the choice of variable at run +time, use the function `set'. + + -- Special Form: setq [symbol form]... + This special form is the most common method of changing a + variable's value. Each SYMBOL is given a new value, which is the + result of evaluating the corresponding FORM. The most-local + existing binding of the symbol is changed. + + `setq' does not evaluate SYMBOL; it sets the symbol that you + write. We say that this argument is "automatically quoted". The + `q' in `setq' stands for "quoted." + + The value of the `setq' form is the value of the last FORM. + + (setq x (1+ 2)) + => 3 + x ; `x' now has a global value. + => 3 + (let ((x 5)) + (setq x 6) ; The local binding of `x' is set. + x) + => 6 + x ; The global value is unchanged. + => 3 + + Note that the first FORM is evaluated, then the first SYMBOL is + set, then the second FORM is evaluated, then the second SYMBOL is + set, and so on: + + (setq x 10 ; Notice that `x' is set before + y (1+ x)) ; the value of `y' is computed. + => 11 + + -- Function: set symbol value + This function sets SYMBOL's value to VALUE, then returns VALUE. + Since `set' is a function, the expression written for SYMBOL is + evaluated to obtain the symbol to set. + + The most-local existing binding of the variable is the binding + that is set; shadowed bindings are not affected. + + (set one 1) + error--> Symbol's value as variable is void: one + (set 'one 1) + => 1 + (set 'two 'one) + => one + (set two 2) ; `two' evaluates to symbol `one'. + => 2 + one ; So it is `one' that was set. + => 2 + (let ((one 1)) ; This binding of `one' is set, + (set 'one 3) ; not the global value. + one) + => 3 + one + => 2 + + If SYMBOL is not actually a symbol, a `wrong-type-argument' error + is signaled. + + (set '(x y) 'z) + error--> Wrong type argument: symbolp, (x y) + + Logically speaking, `set' is a more fundamental primitive than + `setq'. Any use of `setq' can be trivially rewritten to use + `set'; `setq' could even be defined as a macro, given the + availability of `set'. However, `set' itself is rarely used; + beginners hardly need to know about it. It is useful only for + choosing at run time which variable to set. For example, the + command `set-variable', which reads a variable name from the user + and then sets the variable, needs to use `set'. + + Common Lisp note: In Common Lisp, `set' always changes the + symbol's special value, ignoring any lexical bindings. In + XEmacs Lisp, all variables and all bindings are (in effect) + special, so `set' always affects the most local existing + binding. + + One other function for setting a variable is designed to add an +element to a list if it is not already present in the list. + + -- Function: add-to-list symbol element + This function sets the variable SYMBOL by consing ELEMENT onto the + old value, if ELEMENT is not already a member of that value. It + returns the resulting list, whether updated or not. The value of + SYMBOL had better be a list already before the call. + + The argument SYMBOL is not implicitly quoted; `add-to-list' is an + ordinary function, like `set' and unlike `setq'. Quote the + argument yourself if that is what you want. + + Here's a scenario showing how to use `add-to-list': + + (setq foo '(a b)) + => (a b) + + (add-to-list 'foo 'c) ;; Add `c'. + => (c a b) + + (add-to-list 'foo 'b) ;; No effect. + => (c a b) + + foo ;; `foo' was changed. + => (c a b) + + An equivalent expression for `(add-to-list 'VAR VALUE)' is this: + + (or (member VALUE VAR) + (setq VAR (cons VALUE VAR))) + + +File: lispref.info, Node: Variable Scoping, Next: Buffer-Local Variables, Prev: Setting Variables, Up: Variables + +16.8 Scoping Rules for Variable Bindings +======================================== + +A given symbol `foo' may have several local variable bindings, +established at different places in the Lisp program, as well as a global +binding. The most recently established binding takes precedence over +the others. + + Local bindings in XEmacs Lisp have "indefinite scope" and "dynamic +extent". "Scope" refers to _where_ textually in the source code the +binding can be accessed. Indefinite scope means that any part of the +program can potentially access the variable binding. "Extent" refers +to _when_, as the program is executing, the binding exists. Dynamic +extent means that the binding lasts as long as the activation of the +construct that established it. + + The combination of dynamic extent and indefinite scope is called +"dynamic scoping". By contrast, most programming languages use +"lexical scoping", in which references to a local variable must be +located textually within the function or block that binds the variable. + + Common Lisp note: Variables declared "special" in Common Lisp are + dynamically scoped, like variables in XEmacs Lisp. + +* Menu: + +* Scope:: Scope means where in the program a value is visible. + Comparison with other languages. +* Extent:: Extent means how long in time a value exists. +* Impl of Scope:: Two ways to implement dynamic scoping. +* Using Scoping:: How to use dynamic scoping carefully and avoid problems. + + +File: lispref.info, Node: Scope, Next: Extent, Up: Variable Scoping + +16.8.1 Scope +------------ + +XEmacs Lisp uses "indefinite scope" for local variable bindings. This +means that any function anywhere in the program text might access a +given binding of a variable. Consider the following function +definitions: + + (defun binder (x) ; `x' is bound in `binder'. + (foo 5)) ; `foo' is some other function. + + (defun user () ; `x' is used in `user'. + (list x)) + + In a lexically scoped language, the binding of `x' in `binder' would +never be accessible in `user', because `user' is not textually +contained within the function `binder'. However, in dynamically scoped +XEmacs Lisp, `user' may or may not refer to the binding of `x' +established in `binder', depending on circumstances: + + * If we call `user' directly without calling `binder' at all, then + whatever binding of `x' is found, it cannot come from `binder'. + + * If we define `foo' as follows and call `binder', then the binding + made in `binder' will be seen in `user': + + (defun foo (lose) + (user)) + + * If we define `foo' as follows and call `binder', then the binding + made in `binder' _will not_ be seen in `user': + + (defun foo (x) + (user)) + + Here, when `foo' is called by `binder', it binds `x'. (The + binding in `foo' is said to "shadow" the one made in `binder'.) + Therefore, `user' will access the `x' bound by `foo' instead of + the one bound by `binder'. + + +File: lispref.info, Node: Extent, Next: Impl of Scope, Prev: Scope, Up: Variable Scoping + +16.8.2 Extent +------------- + +"Extent" refers to the time during program execution that a variable +name is valid. In XEmacs Lisp, a variable is valid only while the form +that bound it is executing. This is called "dynamic extent". "Local" +or "automatic" variables in most languages, including C and Pascal, +have dynamic extent. + + One alternative to dynamic extent is "indefinite extent". This +means that a variable binding can live on past the exit from the form +that made the binding. Common Lisp and Scheme, for example, support +this, but XEmacs Lisp does not. + + To illustrate this, the function below, `make-add', returns a +function that purports to add N to its own argument M. This would work +in Common Lisp, but it does not work as intended in XEmacs Lisp, +because after the call to `make-add' exits, the variable `n' is no +longer bound to the actual argument 2. + + (defun make-add (n) + (function (lambda (m) (+ n m)))) ; Return a function. + => make-add + (fset 'add2 (make-add 2)) ; Define function `add2' + ; with `(make-add 2)'. + => (lambda (m) (+ n m)) + (add2 4) ; Try to add 2 to 4. + error--> Symbol's value as variable is void: n + + Some Lisp dialects have "closures", objects that are like functions +but record additional variable bindings. XEmacs Lisp does not have +closures. + + +File: lispref.info, Node: Impl of Scope, Next: Using Scoping, Prev: Extent, Up: Variable Scoping + +16.8.3 Implementation of Dynamic Scoping +---------------------------------------- + +A simple sample implementation (which is not how XEmacs Lisp actually +works) may help you understand dynamic binding. This technique is +called "deep binding" and was used in early Lisp systems. + + Suppose there is a stack of bindings: variable-value pairs. At entry +to a function or to a `let' form, we can push bindings on the stack for +the arguments or local variables created there. We can pop those +bindings from the stack at exit from the binding construct. + + We can find the value of a variable by searching the stack from top +to bottom for a binding for that variable; the value from that binding +is the value of the variable. To set the variable, we search for the +current binding, then store the new value into that binding. + + As you can see, a function's bindings remain in effect as long as it +continues execution, even during its calls to other functions. That is +why we say the extent of the binding is dynamic. And any other function +can refer to the bindings, if it uses the same variables while the +bindings are in effect. That is why we say the scope is indefinite. + + The actual implementation of variable scoping in XEmacs Lisp uses a +technique called "shallow binding". Each variable has a standard place +in which its current value is always found--the value cell of the +symbol. + + In shallow binding, setting the variable works by storing a value in +the value cell. Creating a new binding works by pushing the old value +(belonging to a previous binding) on a stack, and storing the local +value in the value cell. Eliminating a binding works by popping the +old value off the stack, into the value cell. + + We use shallow binding because it has the same results as deep +binding, but runs faster, since there is never a need to search for a +binding. + + +File: lispref.info, Node: Using Scoping, Prev: Impl of Scope, Up: Variable Scoping + +16.8.4 Proper Use of Dynamic Scoping +------------------------------------ + +Binding a variable in one function and using it in another is a +powerful technique, but if used without restraint, it can make programs +hard to understand. There are two clean ways to use this technique: + + * Use or bind the variable only in a few related functions, written + close together in one file. Such a variable is used for + communication within one program. + + You should write comments to inform other programmers that they + can see all uses of the variable before them, and to advise them + not to add uses elsewhere. + + * Give the variable a well-defined, documented meaning, and make all + appropriate functions refer to it (but not bind it or set it) + wherever that meaning is relevant. For example, the variable + `case-fold-search' is defined as "non-`nil' means ignore case when + searching"; various search and replace functions refer to it + directly or through their subroutines, but do not bind or set it. + + Then you can bind the variable in other programs, knowing reliably + what the effect will be. + + In either case, you should define the variable with `defvar'. This +helps other people understand your program by telling them to look for +inter-function usage. It also avoids a warning from the byte compiler. +Choose the variable's name to avoid name conflicts--don't use short +names like `x'. + + +File: lispref.info, Node: Buffer-Local Variables, Next: Variable Aliases, Prev: Variable Scoping, Up: Variables + +16.9 Buffer-Local Variables +=========================== + +Global and local variable bindings are found in most programming +languages in one form or another. XEmacs also supports another, unusual +kind of variable binding: "buffer-local" bindings, which apply only to +one buffer. XEmacs Lisp is meant for programming editing commands, and +having different values for a variable in different buffers is an +important customization method. + +* Menu: + +* Intro to Buffer-Local:: Introduction and concepts. +* Creating Buffer-Local:: Creating and destroying buffer-local bindings. +* Default Value:: The default value is seen in buffers + that don't have their own local values. + + +File: lispref.info, Node: Intro to Buffer-Local, Next: Creating Buffer-Local, Up: Buffer-Local Variables + +16.9.1 Introduction to Buffer-Local Variables +--------------------------------------------- + +A buffer-local variable has a buffer-local binding associated with a +particular buffer. The binding is in effect when that buffer is +current; otherwise, it is not in effect. If you set the variable while +a buffer-local binding is in effect, the new value goes in that binding, +so the global binding is unchanged; this means that the change is +visible in that buffer alone. + + A variable may have buffer-local bindings in some buffers but not in +others. The global binding is shared by all the buffers that don't have +their own bindings. Thus, if you set the variable in a buffer that does +not have a buffer-local binding for it, the new value is visible in all +buffers except those with buffer-local bindings. (Here we are assuming +that there are no `let'-style local bindings to complicate the issue.) + + The most common use of buffer-local bindings is for major modes to +change variables that control the behavior of commands. For example, C +mode and Lisp mode both set the variable `paragraph-start' to specify +that only blank lines separate paragraphs. They do this by making the +variable buffer-local in the buffer that is being put into C mode or +Lisp mode, and then setting it to the new value for that mode. + + The usual way to make a buffer-local binding is with +`make-local-variable', which is what major mode commands use. This +affects just the current buffer; all other buffers (including those yet +to be created) continue to share the global value. + + A more powerful operation is to mark the variable as "automatically +buffer-local" by calling `make-variable-buffer-local'. You can think +of this as making the variable local in all buffers, even those yet to +be created. More precisely, the effect is that setting the variable +automatically makes the variable local to the current buffer if it is +not already so. All buffers start out by sharing the global value of +the variable as usual, but any `setq' creates a buffer-local binding +for the current buffer. The new value is stored in the buffer-local +binding, leaving the (default) global binding untouched. The global +value can no longer be changed with `setq'; you need to use +`setq-default' to do that. + + Local variables in a file you edit are also represented by +buffer-local bindings for the buffer that holds the file within XEmacs. +*Note Auto Major Mode::. + + +File: lispref.info, Node: Creating Buffer-Local, Next: Default Value, Prev: Intro to Buffer-Local, Up: Buffer-Local Variables + +16.9.2 Creating and Deleting Buffer-Local Bindings +-------------------------------------------------- + + -- Command: make-local-variable variable + This function creates a buffer-local binding in the current buffer + for VARIABLE (a symbol). Other buffers are not affected. The + value returned is VARIABLE. + + The buffer-local value of VARIABLE starts out as the same value + VARIABLE previously had. If VARIABLE was void, it remains void. + + ;; In buffer `b1': + (setq foo 5) ; Affects all buffers. + => 5 + (make-local-variable 'foo) ; Now it is local in `b1'. + => foo + foo ; That did not change + => 5 ; the value. + (setq foo 6) ; Change the value + => 6 ; in `b1'. + foo + => 6 + + ;; In buffer `b2', the value hasn't changed. + (save-excursion + (set-buffer "b2") + foo) + => 5 + + Making a variable buffer-local within a `let'-binding for that + variable does not work. This is because `let' does not distinguish + between different kinds of bindings; it knows only which variable + the binding was made for. + + *Please note:* do not use `make-local-variable' for a hook + variable. Instead, use `make-local-hook'. *Note Hooks::. + + -- Command: make-variable-buffer-local variable + This function marks VARIABLE (a symbol) automatically + buffer-local, so that any subsequent attempt to set it will make it + local to the current buffer at the time. + + The value returned is VARIABLE. + + -- Function: local-variable-p variable buffer &optional after-set + This returns `t' if VARIABLE is buffer-local in buffer BUFFER; + else `nil'. + + If optional third arg AFTER-SET is non-`nil', return `t' if SYMBOL + would be buffer-local after it is set, regardless of whether it is + so presently. + + A `nil' value for BUFFER is _not_ the same as `(current-buffer)', + but means "no buffer". Specifically: + + If BUFFER is `nil' and AFTER-SET is `nil', a return value of `t' + indicates that the variable is one of the special built-in + variables that is always buffer-local. (This includes + `buffer-file-name', `buffer-read-only', `buffer-undo-list', and + others.) + + If BUFFER is `nil' and AFTER-SET is `t', a return value of `t' + indicates that the variable has had `make-variable-buffer-local' + applied to it. + + -- Function: buffer-local-variables &optional buffer + This function returns a list describing the buffer-local variables + in buffer BUFFER. It returns an association list (*note + Association Lists::) in which each association contains one + buffer-local variable and its value. When a buffer-local variable + is void in BUFFER, then it appears directly in the resulting list. + If BUFFER is omitted, the current buffer is used. + + (make-local-variable 'foobar) + (makunbound 'foobar) + (make-local-variable 'bind-me) + (setq bind-me 69) + (setq lcl (buffer-local-variables)) + ;; First, built-in variables local in all buffers: + => ((mark-active . nil) + (buffer-undo-list nil) + (mode-name . "Fundamental") + ... + ;; Next, non-built-in local variables. + ;; This one is local and void: + foobar + ;; This one is local and nonvoid: + (bind-me . 69)) + + Note that storing new values into the CDRs of cons cells in this + list does _not_ change the local values of the variables. + + -- Command: kill-local-variable variable + This function deletes the buffer-local binding (if any) for + VARIABLE (a symbol) in the current buffer. As a result, the + global (default) binding of VARIABLE becomes visible in this + buffer. Usually this results in a change in the value of + VARIABLE, since the global value is usually different from the + buffer-local value just eliminated. + + If you kill the local binding of a variable that automatically + becomes local when set, this makes the global value visible in the + current buffer. However, if you set the variable again, that will + once again create a local binding for it. + + `kill-local-variable' returns VARIABLE. + + This function is a command because it is sometimes useful to kill + one buffer-local variable interactively, just as it is useful to + create buffer-local variables interactively. + + -- Function: kill-all-local-variables + This function eliminates all the buffer-local variable bindings of + the current buffer except for variables marked as "permanent". As + a result, the buffer will see the default values of most variables. + + This function also resets certain other information pertaining to + the buffer: it sets the local keymap to `nil', the syntax table to + the value of `standard-syntax-table', and the abbrev table to the + value of `fundamental-mode-abbrev-table'. + + Every major mode command begins by calling this function, which + has the effect of switching to Fundamental mode and erasing most + of the effects of the previous major mode. To ensure that this + does its job, the variables that major modes set should not be + marked permanent. + + `kill-all-local-variables' returns `nil'. + + A local variable is "permanent" if the variable name (a symbol) has a +`permanent-local' property that is non-`nil'. Permanent locals are +appropriate for data pertaining to where the file came from or how to +save it, rather than with how to edit the contents. + + +File: lispref.info, Node: Default Value, Prev: Creating Buffer-Local, Up: Buffer-Local Variables + +16.9.3 The Default Value of a Buffer-Local Variable +--------------------------------------------------- + +The global value of a variable with buffer-local bindings is also +called the "default" value, because it is the value that is in effect +except when specifically overridden. + + The functions `default-value' and `setq-default' access and change a +variable's default value regardless of whether the current buffer has a +buffer-local binding. For example, you could use `setq-default' to +change the default setting of `paragraph-start' for most buffers; and +this would work even when you are in a C or Lisp mode buffer that has a +buffer-local value for this variable. + + The special forms `defvar' and `defconst' also set the default value +(if they set the variable at all), rather than any local value. + + -- Function: default-value symbol + This function returns SYMBOL's default value. This is the value + that is seen in buffers that do not have their own values for this + variable. If SYMBOL is not buffer-local, this is equivalent to + `symbol-value' (*note Accessing Variables::). + + -- Function: default-boundp symbol + The function `default-boundp' tells you whether SYMBOL's default + value is nonvoid. If `(default-boundp 'foo)' returns `nil', then + `(default-value 'foo)' would get an error. + + `default-boundp' is to `default-value' as `boundp' is to + `symbol-value'. + + -- Special Form: setq-default symbol value + This sets the default value of SYMBOL to VALUE. It does not + evaluate SYMBOL, but does evaluate VALUE. The value of the + `setq-default' form is VALUE. + + If a SYMBOL is not buffer-local for the current buffer, and is not + marked automatically buffer-local, `setq-default' has the same + effect as `setq'. If SYMBOL is buffer-local for the current + buffer, then this changes the value that other buffers will see + (as long as they don't have a buffer-local value), but not the + value that the current buffer sees. + + ;; In buffer `foo': + (make-local-variable 'local) + => local + (setq local 'value-in-foo) + => value-in-foo + (setq-default local 'new-default) + => new-default + local + => value-in-foo + (default-value 'local) + => new-default + + ;; In (the new) buffer `bar': + local + => new-default + (default-value 'local) + => new-default + (setq local 'another-default) + => another-default + (default-value 'local) + => another-default + + ;; Back in buffer `foo': + local + => value-in-foo + (default-value 'local) + => another-default + + -- Function: set-default symbol value + This function is like `setq-default', except that SYMBOL is + evaluated. + + (set-default (car '(a b c)) 23) + => 23 + (default-value 'a) + => 23 + + +File: lispref.info, Node: Variable Aliases, Prev: Buffer-Local Variables, Up: Variables + +16.10 Variable Aliases +====================== + +You can define a variable as an "alias" for another. Any time you +reference the former variable, the current value of the latter is +returned. Any time you change the value of the former variable, the +value of the latter is actually changed. This is useful in cases where +you want to rename a variable but still make old code work (*note +Obsoleteness::). + + -- Function: defvaralias variable alias + This function defines VARIABLE as an alias for ALIAS. + Thenceforth, any operations performed on VARIABLE will actually be + performed on ALIAS. Both VARIABLE and ALIAS should be symbols. + If ALIAS is `nil', remove any aliases for VARIABLE. ALIAS can + itself be aliased, and the chain of variable aliases will be + followed appropriately. If VARIABLE already has a value, this + value will be shadowed until the alias is removed, at which point + it will be restored. Currently VARIABLE cannot be a built-in + variable, a variable that has a buffer-local value in any buffer, + or the symbols `nil' or `t'. + + -- Function: variable-alias variable &optional follow-past-lisp-magic + If VARIABLE is aliased to another variable, this function returns + that variable. VARIABLE should be a symbol. If VARIABLE is not + aliased, this function returns `nil'. + + -- Function: indirect-variable object &optional follow-past-lisp-magic + This function returns the variable at the end of OBJECT's + variable-alias chain. If OBJECT is a symbol, follow all variable + aliases and return the final (non-aliased) symbol. If OBJECT is + not a symbol, just return it. Signal a + `cyclic-variable-indirection' error if there is a loop in the + variable chain of symbols. + + +File: lispref.info, Node: Functions and Commands, Next: Macros, Prev: Variables, Up: Top + +17 Functions and Commands +************************* + +A Lisp program is composed mainly of Lisp functions. This chapter +explains what functions are, how they accept arguments, and how to +define them. + +* Menu: + +* What Is a Function:: Lisp functions vs. primitives; terminology. +* Lambda Expressions:: How functions are expressed as Lisp objects. +* Function Names:: A symbol can serve as the name of a function. +* Defining Functions:: Lisp expressions for defining functions. +* Calling Functions:: How to use an existing function. +* Mapping Functions:: Applying a function to each element of a list, etc. +* Anonymous Functions:: Lambda expressions are functions with no names. +* Function Cells:: Accessing or setting the function definition + of a symbol. +* Inline Functions:: Defining functions that the compiler will open code. +* Related Topics:: Cross-references to specific Lisp primitives + that have a special bearing on how functions work. + + +File: lispref.info, Node: What Is a Function, Next: Lambda Expressions, Up: Functions and Commands + +17.1 What Is a Function? +======================== + +In a general sense, a function is a rule for carrying on a computation +given several values called "arguments". The result of the computation +is called the value of the function. The computation can also have +side effects: lasting changes in the values of variables or the +contents of data structures. + + Here are important terms for functions in XEmacs Lisp and for other +function-like objects. + +"function" + In XEmacs Lisp, a "function" is anything that can be applied to + arguments in a Lisp program. In some cases, we use it more + specifically to mean a function written in Lisp. Special forms and + macros are not functions. + +"command" + A "command" is a possible definition for a key sequence--we count + mouse events and menu accesses as key sequences for this purpose. + More formally, within XEmacs lisp, a command is something that + `command-execute' can invoke. + + Some functions are commands; a function written in Lisp is a + command if it contains an interactive declaration. A trivial + interactive declaration is a line `(interactive)' immediately + after the documentation string. For more complex examples, with + prompting and completion, see *Note Defining Commands::. Such a + function can be called from Lisp expressions like other functions; + in this case, the fact that the function is a command makes no + difference. + + Keyboard macros (strings and vectors) are commands also, even + though they are not functions. A symbol is a command if its + function definition is a command; such symbols can be invoked with + `M-x'. The symbol is a function as well if the definition is a + function. + + In the case where you want to call a command in reaction to a + user-generated event, you'll need to bind it to that event. For + how to do this, see *Note Key Binding Commands::. *Note Command + Overview::. + +"keystroke command" + A "keystroke command" is a command that is bound to a key sequence + (typically one to three keystrokes). The distinction is made here + merely to avoid confusion with the meaning of "command" in + non-Emacs editors; for Lisp programs, the distinction is normally + unimportant. + +"primitive" + A "primitive" is a function callable from Lisp that is written in + C, such as `car' or `append'. These functions are also called + "built-in" functions or "subrs". (Special forms are also + considered primitives.) + + Usually the reason that a function is a primitives is because it is + fundamental, because it provides a low-level interface to operating + system services, or because it needs to run fast. Primitives can + be modified or added only by changing the C sources and + recompiling the editor. See *Note Writing Lisp Primitives: + (internals)Writing Lisp Primitives. + +"lambda expression" + A "lambda expression" is a function written in Lisp. These are + described in the following section. *Note Lambda Expressions::. + +"special form" + A "special form" is a primitive that is like a function but does + not evaluate all of its arguments in the usual way. It may + evaluate only some of the arguments, or may evaluate them in an + unusual order, or several times. Many special forms are described + in *Note Control Structures::. + +"macro" + A "macro" is a construct defined in Lisp by the programmer. It + differs from a function in that it translates a Lisp expression + that you write into an equivalent expression to be evaluated + instead of the original expression. Macros enable Lisp + programmers to do the sorts of things that special forms can do. + *Note Macros::, for how to define and use macros. + +"compiled function" + A "compiled function" is a function that has been compiled by the + byte compiler. *Note Compiled-Function Type::. + + -- Function: subrp object + This function returns `t' if OBJECT is a built-in function (i.e., + a Lisp primitive). + + (subrp 'message) ; `message' is a symbol, + => nil ; not a subr object. + (subrp (symbol-function 'message)) + => t + + -- Function: compiled-function-p object + This function returns `t' if OBJECT is a compiled function. For + example: + + (compiled-function-p (symbol-function 'next-line)) + => t + + +File: lispref.info, Node: Lambda Expressions, Next: Function Names, Prev: What Is a Function, Up: Functions and Commands + +17.2 Lambda Expressions +======================= + +A function written in Lisp is a list that looks like this: + + (lambda (ARG-VARIABLES...) + [DOCUMENTATION-STRING] + [INTERACTIVE-DECLARATION] + BODY-FORMS...) + +Such a list is called a "lambda expression". In XEmacs Lisp, it +actually is valid as an expression--it evaluates to itself. In some +other Lisp dialects, a lambda expression is not a valid expression at +all. In either case, its main use is not to be evaluated as an +expression, but to be called as a function. + +* Menu: + +* Lambda Components:: The parts of a lambda expression. +* Simple Lambda:: A simple example. +* Argument List:: Details and special features of argument lists. +* Function Documentation:: How to put documentation in a function. + + +File: lispref.info, Node: Lambda Components, Next: Simple Lambda, Up: Lambda Expressions + +17.2.1 Components of a Lambda Expression +---------------------------------------- + +A function written in Lisp (a "lambda expression") is a list that looks +like this: + + (lambda (ARG-VARIABLES...) + [DOCUMENTATION-STRING] + [INTERACTIVE-DECLARATION] + BODY-FORMS...) + +The first element of a lambda expression is always the symbol `lambda'. +This indicates that the list represents a function. The reason +functions are defined to start with `lambda' is so that other lists, +intended for other uses, will not accidentally be valid as functions. + + The second element is a list of symbols-the argument variable names. +This is called the "lambda list". When a Lisp function is called, the +argument values are matched up against the variables in the lambda +list, which are given local bindings with the values provided. *Note +Local Variables::. + + The documentation string is a Lisp string object placed within the +function definition to describe the function for the XEmacs help +facilities. *Note Function Documentation::. + + The interactive declaration is a list of the form `(interactive +CODE-STRING)'. This declares how to provide arguments if the function +is used interactively. Functions with this declaration are called +"commands"; they can be called using `M-x' or bound to a key. +Functions not intended to be called in this way should not have +interactive declarations. *Note Defining Commands::, for how to write +an interactive declaration. + + The rest of the elements are the "body" of the function: the Lisp +code to do the work of the function (or, as a Lisp programmer would say, +"a list of Lisp forms to evaluate"). The value returned by the +function is the value returned by the last element of the body. + + +File: lispref.info, Node: Simple Lambda, Next: Argument List, Prev: Lambda Components, Up: Lambda Expressions + +17.2.2 A Simple Lambda-Expression Example +----------------------------------------- + +Consider for example the following function: + + (lambda (a b c) (+ a b c)) + +We can call this function by writing it as the CAR of an expression, +like this: + + ((lambda (a b c) (+ a b c)) + 1 2 3) + +This call evaluates the body of the lambda expression with the variable +`a' bound to 1, `b' bound to 2, and `c' bound to 3. Evaluation of the +body adds these three numbers, producing the result 6; therefore, this +call to the function returns the value 6. + + Note that the arguments can be the results of other function calls, +as in this example: + + ((lambda (a b c) (+ a b c)) + 1 (* 2 3) (- 5 4)) + +This evaluates the arguments `1', `(* 2 3)', and `(- 5 4)' from left to +right. Then it applies the lambda expression to the argument values 1, +6 and 1 to produce the value 8. + + It is not often useful to write a lambda expression as the CAR of a +form in this way. You can get the same result, of making local +variables and giving them values, using the special form `let' (*note +Local Variables::). And `let' is clearer and easier to use. In +practice, lambda expressions are either stored as the function +definitions of symbols, to produce named functions, or passed as +arguments to other functions (*note Anonymous Functions::). + + However, calls to explicit lambda expressions were very useful in the +old days of Lisp, before the special form `let' was invented. At that +time, they were the only way to bind and initialize local variables. + + +File: lispref.info, Node: Argument List, Next: Function Documentation, Prev: Simple Lambda, Up: Lambda Expressions + +17.2.3 Advanced Features of Argument Lists +------------------------------------------ + +Our simple sample function, `(lambda (a b c) (+ a b c))', specifies +three argument variables, so it must be called with three arguments: if +you try to call it with only two arguments or four arguments, you get a +`wrong-number-of-arguments' error. + + It is often convenient to write a function that allows certain +arguments to be omitted. For example, the function `substring' accepts +three arguments--a string, the start index and the end index--but the +third argument defaults to the LENGTH of the string if you omit it. It +is also convenient for certain functions to accept an indefinite number +of arguments, as the functions `list' and `+' do. + + To specify optional arguments that may be omitted when a function is +called, simply include the keyword `&optional' before the optional +arguments. To specify a list of zero or more extra arguments, include +the keyword `&rest' before one final argument. + + Thus, the complete syntax for an argument list is as follows: + + (REQUIRED-VARS... + [&optional OPTIONAL-VARS...] + [&rest REST-VAR]) + +The square brackets indicate that the `&optional' and `&rest' clauses, +and the variables that follow them, are optional. + + A call to the function requires one actual argument for each of the +REQUIRED-VARS. There may be actual arguments for zero or more of the +OPTIONAL-VARS, and there cannot be any actual arguments beyond that +unless the lambda list uses `&rest'. In that case, there may be any +number of extra actual arguments. + + If actual arguments for the optional and rest variables are omitted, +then they always default to `nil'. There is no way for the function to +distinguish between an explicit argument of `nil' and an omitted +argument. However, the body of the function is free to consider `nil' +an abbreviation for some other meaningful value. This is what +`substring' does; `nil' as the third argument to `substring' means to +use the length of the string supplied. + + Common Lisp note: Common Lisp allows the function to specify what + default value to use when an optional argument is omitted; XEmacs + Lisp always uses `nil'. + + For example, an argument list that looks like this: + + (a b &optional c d &rest e) + +binds `a' and `b' to the first two actual arguments, which are +required. If one or two more arguments are provided, `c' and `d' are +bound to them respectively; any arguments after the first four are +collected into a list and `e' is bound to that list. If there are only +two arguments, `c' is `nil'; if two or three arguments, `d' is `nil'; +if four arguments or fewer, `e' is `nil'. + + There is no way to have required arguments following optional +ones--it would not make sense. To see why this must be so, suppose +that `c' in the example were optional and `d' were required. Suppose +three actual arguments are given; which variable would the third +argument be for? Similarly, it makes no sense to have any more +arguments (either required or optional) after a `&rest' argument. + + Here are some examples of argument lists and proper calls: + + ((lambda (n) (1+ n)) ; One required: + 1) ; requires exactly one argument. + => 2 + ((lambda (n &optional n1) ; One required and one optional: + (if n1 (+ n n1) (1+ n))) ; 1 or 2 arguments. + 1 2) + => 3 + ((lambda (n &rest ns) ; One required and one rest: + (+ n (apply '+ ns))) ; 1 or more arguments. + 1 2 3 4 5) + => 15 + + +File: lispref.info, Node: Function Documentation, Prev: Argument List, Up: Lambda Expressions + +17.2.4 Documentation Strings of Functions +----------------------------------------- + +A lambda expression may optionally have a "documentation string" just +after the lambda list. This string does not affect execution of the +function; it is a kind of comment, but a systematized comment which +actually appears inside the Lisp world and can be used by the XEmacs +help facilities. *Note Documentation::, for how the +DOCUMENTATION-STRING is accessed. + + It is a good idea to provide documentation strings for all the +functions in your program, even those that are only called from within +your program. Documentation strings are like comments, except that they +are easier to access. + + The first line of the documentation string should stand on its own, +because `apropos' displays just this first line. It should consist of +one or two complete sentences that summarize the function's purpose. + + The start of the documentation string is usually indented in the +source file, but since these spaces come before the starting +double-quote, they are not part of the string. Some people make a +practice of indenting any additional lines of the string so that the +text lines up in the program source. _This is a mistake._ The +indentation of the following lines is inside the string; what looks +nice in the source code will look ugly when displayed by the help +commands. + + You may wonder how the documentation string could be optional, since +there are required components of the function that follow it (the body). +Since evaluation of a string returns that string, without any side +effects, it has no effect if it is not the last form in the body. +Thus, in practice, there is no confusion between the first form of the +body and the documentation string; if the only body form is a string +then it serves both as the return value and as the documentation. + + +File: lispref.info, Node: Function Names, Next: Defining Functions, Prev: Lambda Expressions, Up: Functions and Commands + +17.3 Naming a Function +====================== + +In most computer languages, every function has a name; the idea of a +function without a name is nonsensical. In Lisp, a function in the +strictest sense has no name. It is simply a list whose first element is +`lambda', or a primitive subr-object. + + However, a symbol can serve as the name of a function. This happens +when you put the function in the symbol's "function cell" (*note Symbol +Components::). Then the symbol itself becomes a valid, callable +function, equivalent to the list or subr-object that its function cell +refers to. The contents of the function cell are also called the +symbol's "function definition". The procedure of using a symbol's +function definition in place of the symbol is called "symbol function +indirection"; see *Note Function Indirection::. + + In practice, nearly all functions are given names in this way and +referred to through their names. For example, the symbol `car' works +as a function and does what it does because the primitive subr-object +`#' is stored in its function cell. + + We give functions names because it is convenient to refer to them by +their names in Lisp expressions. For primitive subr-objects such as +`#', names are the only way you can refer to them: there is +no read syntax for such objects. For functions written in Lisp, the +name is more convenient to use in a call than an explicit lambda +expression. Also, a function with a name can refer to itself--it can +be recursive. Writing the function's name in its own definition is much +more convenient than making the function definition point to itself +(something that is not impossible but that has various disadvantages in +practice). + + We often identify functions with the symbols used to name them. For +example, we often speak of "the function `car'", not distinguishing +between the symbol `car' and the primitive subr-object that is its +function definition. For most purposes, there is no need to +distinguish. + + Even so, keep in mind that a function need not have a unique name. +While a given function object _usually_ appears in the function cell of +only one symbol, this is just a matter of convenience. It is easy to +store it in several symbols using `fset'; then each of the symbols is +equally well a name for the same function. + + A symbol used as a function name may also be used as a variable; +these two uses of a symbol are independent and do not conflict. + + +File: lispref.info, Node: Defining Functions, Next: Calling Functions, Prev: Function Names, Up: Functions and Commands + +17.4 Defining Functions +======================= + +We usually give a name to a function when it is first created. This is +called "defining a function", and it is done with the `defun' special +form. + + -- Special Form: defun name argument-list body-forms + `defun' is the usual way to define new Lisp functions. It defines + the symbol NAME as a function that looks like this: + + (lambda ARGUMENT-LIST . BODY-FORMS) + + `defun' stores this lambda expression in the function cell of + NAME. It returns the value NAME, but usually we ignore this value. + + As described previously (*note Lambda Expressions::), + ARGUMENT-LIST is a list of argument names and may include the + keywords `&optional' and `&rest'. Also, the first two forms in + BODY-FORMS may be a documentation string and an interactive + declaration. + + There is no conflict if the same symbol NAME is also used as a + variable, since the symbol's value cell is independent of the + function cell. *Note Symbol Components::. + + Here are some examples: + + (defun foo () 5) + => foo + (foo) + => 5 + + (defun bar (a &optional b &rest c) + (list a b c)) + => bar + (bar 1 2 3 4 5) + => (1 2 (3 4 5)) + (bar 1) + => (1 nil nil) + (bar) + error--> Wrong number of arguments. + + (defun capitalize-backwards () + "Upcase the last letter of a word." + (interactive) + (backward-word 1) + (forward-word 1) + (backward-char 1) + (capitalize-word 1)) + => capitalize-backwards + + Be careful not to redefine existing functions unintentionally. + `defun' redefines even primitive functions such as `car' without + any hesitation or notification. Redefining a function already + defined is often done deliberately, and there is no way to + distinguish deliberate redefinition from unintentional + redefinition. + + -- Function: define-function name definition + -- Function: defalias name definition + These equivalent special forms define the symbol NAME as a + function, with definition DEFINITION (which can be any valid Lisp + function). + + The proper place to use `define-function' or `defalias' is where a + specific function name is being defined--especially where that + name appears explicitly in the source file being loaded. This is + because `define-function' and `defalias' record which file defined + the function, just like `defun'. (*note Unloading::). + + By contrast, in programs that manipulate function definitions for + other purposes, it is better to use `fset', which does not keep + such records. + + See also `defsubst', which defines a function like `defun' and tells +the Lisp compiler to open-code it. *Note Inline Functions::. + + +File: lispref.info, Node: Calling Functions, Next: Mapping Functions, Prev: Defining Functions, Up: Functions and Commands + +17.5 Calling Functions +====================== + +Defining functions is only half the battle. Functions don't do +anything until you "call" them, i.e., tell them to run. Calling a +function is also known as "invocation". + + The most common way of invoking a function is by evaluating a list. +For example, evaluating the list `(concat "a" "b")' calls the function +`concat' with arguments `"a"' and `"b"'. *Note Evaluation::, for a +description of evaluation. + + When you write a list as an expression in your program, the function +name is part of the program. This means that you choose which function +to call, and how many arguments to give it, when you write the program. +Usually that's just what you want. Occasionally you need to decide at +run time which function to call. To do that, use the functions +`funcall' and `apply'. + + -- Function: funcall function &rest arguments + `funcall' calls FUNCTION with ARGUMENTS, and returns whatever + FUNCTION returns. + + Since `funcall' is a function, all of its arguments, including + FUNCTION, are evaluated before `funcall' is called. This means + that you can use any expression to obtain the function to be + called. It also means that `funcall' does not see the expressions + you write for the ARGUMENTS, only their values. These values are + _not_ evaluated a second time in the act of calling FUNCTION; + `funcall' enters the normal procedure for calling a function at the + place where the arguments have already been evaluated. + + The argument FUNCTION must be either a Lisp function or a + primitive function. Special forms and macros are not allowed, + because they make sense only when given the "unevaluated" argument + expressions. `funcall' cannot provide these because, as we saw + above, it never knows them in the first place. + + (setq f 'list) + => list + (funcall f 'x 'y 'z) + => (x y z) + (funcall f 'x 'y '(z)) + => (x y (z)) + (funcall 'and t nil) + error--> Invalid function: # + + Compare these example with the examples of `apply'. + + -- Function: apply function &rest arguments + `apply' calls FUNCTION with ARGUMENTS, just like `funcall' but + with one difference: the last of ARGUMENTS is a list of arguments + to give to FUNCTION, rather than a single argument. We also say + that `apply' "spreads" this list so that each individual element + becomes an argument. + + `apply' returns the result of calling FUNCTION. As with + `funcall', FUNCTION must either be a Lisp function or a primitive + function; special forms and macros do not make sense in `apply'. + + (setq f 'list) + => list + (apply f 'x 'y 'z) + error--> Wrong type argument: listp, z + (apply '+ 1 2 '(3 4)) + => 10 + (apply '+ '(1 2 3 4)) + => 10 + + (apply 'append '((a b c) nil (x y z) nil)) + => (a b c x y z) + + For an interesting example of using `apply', see the description of + `mapcar', in *Note Mapping Functions::. + + It is common for Lisp functions to accept functions as arguments or +find them in data structures (especially in hook variables and property +lists) and call them using `funcall' or `apply'. Functions that accept +function arguments are often called "functionals". + + Sometimes, when you call a functional, it is useful to supply a no-op +function as the argument. Here are two different kinds of no-op +function: + + -- Function: identity arg + This function returns ARG and has no side effects. + + -- Command: ignore &rest args + This function ignores any arguments and returns `nil'. + + +File: lispref.info, Node: Mapping Functions, Next: Anonymous Functions, Prev: Calling Functions, Up: Functions and Commands + +17.6 Mapping Functions +====================== + +A "mapping function" applies a given function to each element of a list +or other collection. XEmacs Lisp has several such functions; `mapcar' +and `mapconcat', which scan a list, are described here. *Note +Creating Symbols::, for the function `mapatoms' which maps over the +symbols in an obarray. + + Mapping functions should never modify the sequence being mapped over. +The results are unpredictable. + + -- Function: mapcar function sequence + `mapcar' applies FUNCTION to each element of SEQUENCE in turn, and + returns a list of the results. + + The argument SEQUENCE can be any kind of sequence; that is, a + list, a vector, a bit vector, or a string. The result is always a + list. The length of the result is the same as the length of + SEQUENCE. + + For example: + + (mapcar 'car '((a b) (c d) (e f))) + => (a c e) + (mapcar '1+ [1 2 3]) + => (2 3 4) + (mapcar 'char-to-string "abc") + => ("a" "b" "c") + + ;; Call each function in `my-hooks'. + (mapcar 'funcall my-hooks) + + (defun mapcar* (f &rest args) + "Apply FUNCTION to successive cars of all ARGS. + Return the list of results." + ;; If no list is exhausted, + (if (not (memq 'nil args)) + ;; apply function to CARs. + (cons (apply f (mapcar 'car args)) + (apply 'mapcar* f + ;; Recurse for rest of elements. + (mapcar 'cdr args))))) + + (mapcar* 'cons '(a b c) '(1 2 3 4)) + => ((a . 1) (b . 2) (c . 3)) + + -- Function: mapconcat function sequence separator + `mapconcat' applies FUNCTION to each element of SEQUENCE: the + results, which must be strings, are concatenated. Between each + pair of result strings, `mapconcat' inserts the string SEPARATOR. + Usually SEPARATOR contains a space or comma or other suitable + punctuation. + + The argument FUNCTION must be a function that can take one + argument and return a string. The argument SEQUENCE can be any + kind of sequence; that is, a list, a vector, a bit vector, or a + string. + + (mapconcat 'symbol-name + '(The cat in the hat) + " ") + => "The cat in the hat" + + (mapconcat (function (lambda (x) (format "%c" (1+ x)))) + "HAL-8000" + "") + => "IBM.9111" + + +File: lispref.info, Node: Anonymous Functions, Next: Function Cells, Prev: Mapping Functions, Up: Functions and Commands + +17.7 Anonymous Functions +======================== + +In Lisp, a function is a list that starts with `lambda', a byte-code +function compiled from such a list, or alternatively a primitive +subr-object; names are "extra". Although usually functions are defined +with `defun' and given names at the same time, it is occasionally more +concise to use an explicit lambda expression--an anonymous function. +Such a list is valid wherever a function name is. + + Any method of creating such a list makes a valid function. Even +this: + + (setq silly (append '(lambda (x)) (list (list '+ (* 3 4) 'x)))) + => (lambda (x) (+ 12 x)) + +This computes a list that looks like `(lambda (x) (+ 12 x))' and makes +it the value (_not_ the function definition!) of `silly'. + + Here is how we might call this function: + + (funcall silly 1) + => 13 + +(It does _not_ work to write `(silly 1)', because this function is not +the _function definition_ of `silly'. We have not given `silly' any +function definition, just a value as a variable.) + + Most of the time, anonymous functions are constants that appear in +your program. For example, you might want to pass one as an argument +to the function `mapcar', which applies any given function to each +element of a list. Here we pass an anonymous function that multiplies +a number by two: + + (defun double-each (list) + (mapcar '(lambda (x) (* 2 x)) list)) + => double-each + (double-each '(2 11)) + => (4 22) + +In such cases, we usually use the special form `function' instead of +simple quotation to quote the anonymous function. + + -- Special Form: function function-object + This special form returns FUNCTION-OBJECT without evaluating it. + In this, it is equivalent to `quote'. However, it serves as a + note to the XEmacs Lisp compiler that FUNCTION-OBJECT is intended + to be used only as a function, and therefore can safely be + compiled. Contrast this with `quote', in *Note Quoting::. + + Using `function' instead of `quote' makes a difference inside a +function or macro that you are going to compile. For example: + + (defun double-each (list) + (mapcar (function (lambda (x) (* 2 x))) list)) + => double-each + (double-each '(2 11)) + => (4 22) + +If this definition of `double-each' is compiled, the anonymous function +is compiled as well. By contrast, in the previous definition where +ordinary `quote' is used, the argument passed to `mapcar' is the +precise list shown: + + (lambda (x) (* x 2)) + +The Lisp compiler cannot assume this list is a function, even though it +looks like one, since it does not know what `mapcar' does with the +list. Perhaps `mapcar' will check that the CAR of the third element is +the symbol `*'! The advantage of `function' is that it tells the +compiler to go ahead and compile the constant function. + + We sometimes write `function' instead of `quote' when quoting the +name of a function, but this usage is just a sort of comment. + + (function SYMBOL) == (quote SYMBOL) == 'SYMBOL + + See `documentation' in *Note Accessing Documentation::, for a +realistic example using `function' and an anonymous function. + + +File: lispref.info, Node: Function Cells, Next: Inline Functions, Prev: Anonymous Functions, Up: Functions and Commands + +17.8 Accessing Function Cell Contents +===================================== + +The "function definition" of a symbol is the object stored in the +function cell of the symbol. The functions described here access, test, +and set the function cell of symbols. + + See also the function `indirect-function' in *Note Function +Indirection::. + + -- Function: symbol-function symbol + This returns the object in the function cell of SYMBOL. If the + symbol's function cell is void, a `void-function' error is + signaled. + + This function does not check that the returned object is a + legitimate function. + + (defun bar (n) (+ n 2)) + => bar + (symbol-function 'bar) + => (lambda (n) (+ n 2)) + (fset 'baz 'bar) + => bar + (symbol-function 'baz) + => bar + + If you have never given a symbol any function definition, we say that +that symbol's function cell is "void". In other words, the function +cell does not have any Lisp object in it. If you try to call such a +symbol as a function, it signals a `void-function' error. + + Note that void is not the same as `nil' or the symbol `void'. The +symbols `nil' and `void' are Lisp objects, and can be stored into a +function cell just as any other object can be (and they can be valid +functions if you define them in turn with `defun'). A void function +cell contains no object whatsoever. + + You can test the voidness of a symbol's function definition with +`fboundp'. After you have given a symbol a function definition, you +can make it void once more using `fmakunbound'. + + -- Function: fboundp symbol + This function returns `t' if SYMBOL has an object in its function + cell, `nil' otherwise. It does not check that the object is a + legitimate function. + + -- Function: fmakunbound symbol + This function makes SYMBOL's function cell void, so that a + subsequent attempt to access this cell will cause a `void-function' + error. (See also `makunbound', in *Note Local Variables::.) + + (defun foo (x) x) + => x + (foo 1) + =>1 + (fmakunbound 'foo) + => x + (foo 1) + error--> Symbol's function definition is void: foo + + -- Function: fset symbol object + This function stores OBJECT in the function cell of SYMBOL. The + result is OBJECT. Normally OBJECT should be a function or the + name of a function, but this is not checked. + + There are three normal uses of this function: + + * Copying one symbol's function definition to another. (In + other words, making an alternate name for a function.) + + * Giving a symbol a function definition that is not a list and + therefore cannot be made with `defun'. For example, you can + use `fset' to give a symbol SYMBOL1 a function definition + which is another symbol SYMBOL2; then SYMBOL1 serves as an + alias for whatever definition SYMBOL2 presently has. + + * In constructs for defining or altering functions. If `defun' + were not a primitive, it could be written in Lisp (as a + macro) using `fset'. + + Here are examples of the first two uses: + + ;; Give `first' the same definition `car' has. + (fset 'first (symbol-function 'car)) + => # + (first '(1 2 3)) + => 1 + + ;; Make the symbol `car' the function definition of `xfirst'. + (fset 'xfirst 'car) + => car + (xfirst '(1 2 3)) + => 1 + (symbol-function 'xfirst) + => car + (symbol-function (symbol-function 'xfirst)) + => # + + ;; Define a named keyboard macro. + (fset 'kill-two-lines "\^u2\^k") + => "\^u2\^k" + + See also the related functions `define-function' and `defalias', + in *Note Defining Functions::. + + When writing a function that extends a previously defined function, +the following idiom is sometimes used: + + (fset 'old-foo (symbol-function 'foo)) + (defun foo () + "Just like old-foo, except more so." + (old-foo) + (more-so)) + +This does not work properly if `foo' has been defined to autoload. In +such a case, when `foo' calls `old-foo', Lisp attempts to define +`old-foo' by loading a file. Since this presumably defines `foo' +rather than `old-foo', it does not produce the proper results. The +only way to avoid this problem is to make sure the file is loaded +before moving aside the old definition of `foo'. + + But it is unmodular and unclean, in any case, for a Lisp file to +redefine a function defined elsewhere. + + +File: lispref.info, Node: Inline Functions, Next: Related Topics, Prev: Function Cells, Up: Functions and Commands + +17.9 Inline Functions +===================== + +You can define an "inline function" by using `defsubst' instead of +`defun'. An inline function works just like an ordinary function +except for one thing: when you compile a call to the function, the +function's definition is open-coded into the caller. + + Making a function inline makes explicit calls run faster. But it +also has disadvantages. For one thing, it reduces flexibility; if you +change the definition of the function, calls already inlined still use +the old definition until you recompile them. Since the flexibility of +redefining functions is an important feature of XEmacs, you should not +make a function inline unless its speed is really crucial. + + Another disadvantage is that making a large function inline can +increase the size of compiled code both in files and in memory. Since +the speed advantage of inline functions is greatest for small +functions, you generally should not make large functions inline. + + It's possible to define a macro to expand into the same code that an +inline function would execute. But the macro would have a limitation: +you can use it only explicitly--a macro cannot be called with `apply', +`mapcar' and so on. Also, it takes some work to convert an ordinary +function into a macro. (*Note Macros::.) To convert it into an inline +function is very easy; simply replace `defun' with `defsubst'. Since +each argument of an inline function is evaluated exactly once, you +needn't worry about how many times the body uses the arguments, as you +do for macros. (*Note Argument Evaluation::.) + + Inline functions can be used and open-coded later on in the same +file, following the definition, just like macros. + + +File: lispref.info, Node: Related Topics, Prev: Inline Functions, Up: Functions and Commands + +17.10 Other Topics Related to Functions +======================================= + +Here is a table of several functions that do things related to function +calling and function definitions. They are documented elsewhere, but +we provide cross references here. + +`apply' + See *Note Calling Functions::. + +`autoload' + See *Note Autoload::. + +`call-interactively' + See *Note Interactive Call::. + +`commandp' + See *Note Interactive Call::. + +`documentation' + See *Note Accessing Documentation::. + +`eval' + See *Note Eval::. + +`funcall' + See *Note Calling Functions::. + +`ignore' + See *Note Calling Functions::. + +`indirect-function' + See *Note Function Indirection::. + +`interactive' + See *Note Using Interactive::. + +`interactive-p' + See *Note Interactive Call::. + +`mapatoms' + See *Note Creating Symbols::. + +`mapcar' + See *Note Mapping Functions::. + +`mapconcat' + See *Note Mapping Functions::. + +`undefined' + See *Note Key Lookup::. + + +File: lispref.info, Node: Macros, Next: Loading, Prev: Functions and Commands, Up: Top + +18 Macros +********* + +"Macros" enable you to define new control constructs and other language +features. A macro is defined much like a function, but instead of +telling how to compute a value, it tells how to compute another Lisp +expression which will in turn compute the value. We call this +expression the "expansion" of the macro. + + Macros can do this because they operate on the unevaluated +expressions for the arguments, not on the argument values as functions +do. They can therefore construct an expansion containing these +argument expressions or parts of them. + + If you are using a macro to do something an ordinary function could +do, just for the sake of speed, consider using an inline function +instead. *Note Inline Functions::. + +* Menu: + +* Simple Macro:: A basic example. +* Expansion:: How, when and why macros are expanded. +* Compiling Macros:: How macros are expanded by the compiler. +* Defining Macros:: How to write a macro definition. +* Backquote:: Easier construction of list structure. +* Problems with Macros:: Don't evaluate the macro arguments too many times. + Don't hide the user's variables. + + +File: lispref.info, Node: Simple Macro, Next: Expansion, Up: Macros + +18.1 A Simple Example of a Macro +================================ + +Suppose we would like to define a Lisp construct to increment a +variable value, much like the `++' operator in C. We would like to +write `(inc x)' and have the effect of `(setq x (1+ x))'. Here's a +macro definition that does the job: + + (defmacro inc (var) + (list 'setq var (list '1+ var))) + + When this is called with `(inc x)', the argument `var' has the value +`x'--_not_ the _value_ of `x'. The body of the macro uses this to +construct the expansion, which is `(setq x (1+ x))'. Once the macro +definition returns this expansion, Lisp proceeds to evaluate it, thus +incrementing `x'. + + +File: lispref.info, Node: Expansion, Next: Compiling Macros, Prev: Simple Macro, Up: Macros + +18.2 Expansion of a Macro Call +============================== + +A macro call looks just like a function call in that it is a list which +starts with the name of the macro. The rest of the elements of the list +are the arguments of the macro. + + Evaluation of the macro call begins like evaluation of a function +call except for one crucial difference: the macro arguments are the +actual expressions appearing in the macro call. They are not evaluated +before they are given to the macro definition. By contrast, the +arguments of a function are results of evaluating the elements of the +function call list. + + Having obtained the arguments, Lisp invokes the macro definition just +as a function is invoked. The argument variables of the macro are bound +to the argument values from the macro call, or to a list of them in the +case of a `&rest' argument. And the macro body executes and returns +its value just as a function body does. + + The second crucial difference between macros and functions is that +the value returned by the macro body is not the value of the macro call. +Instead, it is an alternate expression for computing that value, also +known as the "expansion" of the macro. The Lisp interpreter proceeds +to evaluate the expansion as soon as it comes back from the macro. + + Since the expansion is evaluated in the normal manner, it may contain +calls to other macros. It may even be a call to the same macro, though +this is unusual. + + You can see the expansion of a given macro call by calling +`macroexpand'. + + -- Function: macroexpand form &optional environment + This function expands FORM, if it is a macro call. If the result + is another macro call, it is expanded in turn, until something + which is not a macro call results. That is the value returned by + `macroexpand'. If FORM is not a macro call to begin with, it is + returned as given. + + Note that `macroexpand' does not look at the subexpressions of + FORM (although some macro definitions may do so). Even if they + are macro calls themselves, `macroexpand' does not expand them. + + The function `macroexpand' does not expand calls to inline + functions. Normally there is no need for that, since a call to an + inline function is no harder to understand than a call to an + ordinary function. + + If ENVIRONMENT is provided, it specifies an alist of macro + definitions that shadow the currently defined macros. Byte + compilation uses this feature. + + (defmacro inc (var) + (list 'setq var (list '1+ var))) + => inc + + (macroexpand '(inc r)) + => (setq r (1+ r)) + + (defmacro inc2 (var1 var2) + (list 'progn (list 'inc var1) (list 'inc var2))) + => inc2 + + (macroexpand '(inc2 r s)) + => (progn (inc r) (inc s)) ; `inc' not expanded here. + + +File: lispref.info, Node: Compiling Macros, Next: Defining Macros, Prev: Expansion, Up: Macros + +18.3 Macros and Byte Compilation +================================ + +You might ask why we take the trouble to compute an expansion for a +macro and then evaluate the expansion. Why not have the macro body +produce the desired results directly? The reason has to do with +compilation. + + When a macro call appears in a Lisp program being compiled, the Lisp +compiler calls the macro definition just as the interpreter would, and +receives an expansion. But instead of evaluating this expansion, it +compiles the expansion as if it had appeared directly in the program. +As a result, the compiled code produces the value and side effects +intended for the macro, but executes at full compiled speed. This would +not work if the macro body computed the value and side effects +itself--they would be computed at compile time, which is not useful. + + In order for compilation of macro calls to work, the macros must be +defined in Lisp when the calls to them are compiled. The compiler has a +special feature to help you do this: if a file being compiled contains a +`defmacro' form, the macro is defined temporarily for the rest of the +compilation of that file. To use this feature, you must define the +macro in the same file where it is used and before its first use. + + Byte-compiling a file executes any `require' calls at top-level in +the file. This is in case the file needs the required packages for +proper compilation. One way to ensure that necessary macro definitions +are available during compilation is to require the files that define +them (*note Named Features::). To avoid loading the macro definition +files when someone _runs_ the compiled program, write +`eval-when-compile' around the `require' calls (*note Eval During +Compile::). + + +File: lispref.info, Node: Defining Macros, Next: Backquote, Prev: Compiling Macros, Up: Macros + +18.4 Defining Macros +==================== + +A Lisp macro is a list whose CAR is `macro'. Its CDR should be a +function; expansion of the macro works by applying the function (with +`apply') to the list of unevaluated argument-expressions from the macro +call. + + It is possible to use an anonymous Lisp macro just like an anonymous +function, but this is never done, because it does not make sense to pass +an anonymous macro to functionals such as `mapcar'. In practice, all +Lisp macros have names, and they are usually defined with the special +form `defmacro'. + + -- Special Form: defmacro name argument-list body-forms... + `defmacro' defines the symbol NAME as a macro that looks like this: + + (macro lambda ARGUMENT-LIST . BODY-FORMS) + + This macro object is stored in the function cell of NAME. The + value returned by evaluating the `defmacro' form is NAME, but + usually we ignore this value. + + The shape and meaning of ARGUMENT-LIST is the same as in a + function, and the keywords `&rest' and `&optional' may be used + (*note Argument List::). Macros may have a documentation string, + but any `interactive' declaration is ignored since macros cannot be + called interactively. + + +File: lispref.info, Node: Backquote, Next: Problems with Macros, Prev: Defining Macros, Up: Macros + +18.5 Backquote +============== + +Macros often need to construct large list structures from a mixture of +constants and nonconstant parts. To make this easier, use the macro +``' (often called "backquote"). + + Backquote allows you to quote a list, but selectively evaluate +elements of that list. In the simplest case, it is identical to the +special form `quote' (*note Quoting::). For example, these two forms +yield identical results: + + `(a list of (+ 2 3) elements) + => (a list of (+ 2 3) elements) + '(a list of (+ 2 3) elements) + => (a list of (+ 2 3) elements) + + The special marker `,' inside of the argument to backquote indicates +a value that isn't constant. Backquote evaluates the argument of `,' +and puts the value in the list structure: + + (list 'a 'list 'of (+ 2 3) 'elements) + => (a list of 5 elements) + `(a list of ,(+ 2 3) elements) + => (a list of 5 elements) + + You can also "splice" an evaluated value into the resulting list, +using the special marker `,@'. The elements of the spliced list become +elements at the same level as the other elements of the resulting list. +The equivalent code without using ``' is often unreadable. Here are +some examples: + + (setq some-list '(2 3)) + => (2 3) + (cons 1 (append some-list '(4) some-list)) + => (1 2 3 4 2 3) + `(1 ,@some-list 4 ,@some-list) + => (1 2 3 4 2 3) + + (setq list '(hack foo bar)) + => (hack foo bar) + (cons 'use + (cons 'the + (cons 'words (append (cdr list) '(as elements))))) + => (use the words foo bar as elements) + `(use the words ,@(cdr list) as elements) + => (use the words foo bar as elements) + + In older versions of Emacs (before XEmacs 19.12 or FSF Emacs + version 19.29), ``' used a different syntax which required an + extra level of parentheses around the entire backquote construct. + Likewise, each `,' or `,@' substitution required an extra level of + parentheses surrounding both the `,' or `,@' and the following + expression. The old syntax required whitespace between the ``', + `,' or `,@' and the following expression. + + This syntax is still accepted, but no longer recommended except for + compatibility with old Emacs versions. + + +File: lispref.info, Node: Problems with Macros, Prev: Backquote, Up: Macros + +18.6 Common Problems Using Macros +================================= + +The basic facts of macro expansion have counterintuitive consequences. +This section describes some important consequences that can lead to +trouble, and rules to follow to avoid trouble. + +* Menu: + +* Argument Evaluation:: The expansion should evaluate each macro arg once. +* Surprising Local Vars:: Local variable bindings in the expansion + require special care. +* Eval During Expansion:: Don't evaluate them; put them in the expansion. +* Repeated Expansion:: Avoid depending on how many times expansion is done. + + +File: lispref.info, Node: Argument Evaluation, Next: Surprising Local Vars, Up: Problems with Macros + +18.6.1 Evaluating Macro Arguments Repeatedly +-------------------------------------------- + +When defining a macro you must pay attention to the number of times the +arguments will be evaluated when the expansion is executed. The +following macro (used to facilitate iteration) illustrates the problem. +This macro allows us to write a simple "for" loop such as one might +find in Pascal. + + (defmacro for (var from init to final do &rest body) + "Execute a simple \"for\" loop. + For example, (for i from 1 to 10 do (print i))." + (list 'let (list (list var init)) + (cons 'while (cons (list '<= var final) + (append body (list (list 'inc var))))))) + => for + + (for i from 1 to 3 do + (setq square (* i i)) + (princ (format "\n%d %d" i square))) + ==> + (let ((i 1)) + (while (<= i 3) + (setq square (* i i)) + (princ (format "%d %d" i square)) + (inc i))) + + -|1 1 + -|2 4 + -|3 9 + => nil + +(The arguments `from', `to', and `do' in this macro are "syntactic +sugar"; they are entirely ignored. The idea is that you will write +noise words (such as `from', `to', and `do') in those positions in the +macro call.) + + Here's an equivalent definition simplified through use of backquote: + + (defmacro for (var from init to final do &rest body) + "Execute a simple \"for\" loop. + For example, (for i from 1 to 10 do (print i))." + `(let ((,var ,init)) + (while (<= ,var ,final) + ,@body + (inc ,var)))) + + Both forms of this definition (with backquote and without) suffer +from the defect that FINAL is evaluated on every iteration. If FINAL +is a constant, this is not a problem. If it is a more complex form, +say `(long-complex-calculation x)', this can slow down the execution +significantly. If FINAL has side effects, executing it more than once +is probably incorrect. + + A well-designed macro definition takes steps to avoid this problem by +producing an expansion that evaluates the argument expressions exactly +once unless repeated evaluation is part of the intended purpose of the +macro. Here is a correct expansion for the `for' macro: + + (let ((i 1) + (max 3)) + (while (<= i max) + (setq square (* i i)) + (princ (format "%d %d" i square)) + (inc i))) + + Here is a macro definition that creates this expansion: + + (defmacro for (var from init to final do &rest body) + "Execute a simple for loop: (for i from 1 to 10 do (print i))." + `(let ((,var ,init) + (max ,final)) + (while (<= ,var max) + ,@body + (inc ,var)))) + + Unfortunately, this introduces another problem. Proceed to the +following node. + + +File: lispref.info, Node: Surprising Local Vars, Next: Eval During Expansion, Prev: Argument Evaluation, Up: Problems with Macros + +18.6.2 Local Variables in Macro Expansions +------------------------------------------ + +In the previous section, the definition of `for' was fixed as follows +to make the expansion evaluate the macro arguments the proper number of +times: + + (defmacro for (var from init to final do &rest body) + "Execute a simple for loop: (for i from 1 to 10 do (print i))." + `(let ((,var ,init) + (max ,final)) + (while (<= ,var max) + ,@body + (inc ,var)))) + +The new definition of `for' has a new problem: it introduces a local +variable named `max' which the user does not expect. This causes +trouble in examples such as the following: + + (let ((max 0)) + (for x from 0 to 10 do + (let ((this (frob x))) + (if (< max this) + (setq max this))))) + +The references to `max' inside the body of the `for', which are +supposed to refer to the user's binding of `max', really access the +binding made by `for'. + + The way to correct this is to use an uninterned symbol instead of +`max' (*note Creating Symbols::). The uninterned symbol can be bound +and referred to just like any other symbol, but since it is created by +`for', we know that it cannot already appear in the user's program. +Since it is not interned, there is no way the user can put it into the +program later. It will never appear anywhere except where put by +`for'. Here is a definition of `for' that works this way: + + (defmacro for (var from init to final do &rest body) + "Execute a simple for loop: (for i from 1 to 10 do (print i))." + (let ((tempvar (make-symbol "max"))) + `(let ((,var ,init) + (,tempvar ,final)) + (while (<= ,var ,tempvar) + ,@body + (inc ,var))))) + +This creates an uninterned symbol named `max' and puts it in the +expansion instead of the usual interned symbol `max' that appears in +expressions ordinarily. + + +File: lispref.info, Node: Eval During Expansion, Next: Repeated Expansion, Prev: Surprising Local Vars, Up: Problems with Macros + +18.6.3 Evaluating Macro Arguments in Expansion +---------------------------------------------- + +Another problem can happen if you evaluate any of the macro argument +expressions during the computation of the expansion, such as by calling +`eval' (*note Eval::). If the argument is supposed to refer to the +user's variables, you may have trouble if the user happens to use a +variable with the same name as one of the macro arguments. Inside the +macro body, the macro argument binding is the most local binding of this +variable, so any references inside the form being evaluated do refer to +it. Here is an example: + + (defmacro foo (a) + (list 'setq (eval a) t)) + => foo + (setq x 'b) + (foo x) ==> (setq b t) + => t ; and `b' has been set. + ;; but + (setq a 'c) + (foo a) ==> (setq a t) + => t ; but this set `a', not `c'. + + It makes a difference whether the user's variable is named `a' or +`x', because `a' conflicts with the macro argument variable `a'. + + Another reason not to call `eval' in a macro definition is that it +probably won't do what you intend in a compiled program. The +byte-compiler runs macro definitions while compiling the program, when +the program's own computations (which you might have wished to access +with `eval') don't occur and its local variable bindings don't exist. + + The safe way to work with the run-time value of an expression is to +put the expression into the macro expansion, so that its value is +computed as part of executing the expansion. + + +File: lispref.info, Node: Repeated Expansion, Prev: Eval During Expansion, Up: Problems with Macros + +18.6.4 How Many Times is the Macro Expanded? +-------------------------------------------- + +Occasionally problems result from the fact that a macro call is +expanded each time it is evaluated in an interpreted function, but is +expanded only once (during compilation) for a compiled function. If the +macro definition has side effects, they will work differently depending +on how many times the macro is expanded. + + In particular, constructing objects is a kind of side effect. If the +macro is called once, then the objects are constructed only once. In +other words, the same structure of objects is used each time the macro +call is executed. In interpreted operation, the macro is reexpanded +each time, producing a fresh collection of objects each time. Usually +this does not matter--the objects have the same contents whether they +are shared or not. But if the surrounding program does side effects on +the objects, it makes a difference whether they are shared. Here is an +example: + + (defmacro empty-object () + (list 'quote (cons nil nil))) + + (defun initialize (condition) + (let ((object (empty-object))) + (if condition + (setcar object condition)) + object)) + +If `initialize' is interpreted, a new list `(nil)' is constructed each +time `initialize' is called. Thus, no side effect survives between +calls. If `initialize' is compiled, then the macro `empty-object' is +expanded during compilation, producing a single "constant" `(nil)' that +is reused and altered each time `initialize' is called. + + One way to avoid pathological cases like this is to think of +`empty-object' as a funny kind of constant, not as a memory allocation +construct. You wouldn't use `setcar' on a constant such as `'(nil)', +so naturally you won't use it on `(empty-object)' either. + + +File: lispref.info, Node: Customization, Up: Top + +19 Writing Customization Definitions +************************************ + +This chapter describes how to declare user options for customization, +and also customization groups for classifying them. We use the term +"customization item" to include both kinds of customization +definitions--as well as face definitions. + +* Menu: + +* Common Keywords:: +* Group Definitions:: +* Variable Definitions:: +* Customization Types:: + + +File: lispref.info, Node: Common Keywords, Next: Group Definitions, Up: Customization + +19.1 Common Keywords for All Kinds of Items +=========================================== + +All kinds of customization declarations (for variables and groups, and +for faces) accept keyword arguments for specifying various information. +This section describes some keywords that apply to all kinds. + + All of these keywords, except `:tag', can be used more than once in +a given item. Each use of the keyword has an independent effect. The +keyword `:tag' is an exception because any given item can only display +one name. + +`:tag NAME' + Use NAME, a string, instead of the item's name, to label the item + in customization menus and buffers. + +`:group GROUP' + Put this customization item in group GROUP. When you use `:group' + in a `defgroup', it makes the new group a subgroup of GROUP. + + If you use this keyword more than once, you can put a single item + into more than one group. Displaying any of those groups will + show this item. Be careful not to overdo this! + +`:link LINK-DATA' + Include an external link after the documentation string for this + item. This is a sentence containing an active field which + references some other documentation. + + There are three alternatives you can use for LINK-DATA: + + `(custom-manual INFO-NODE)' + Link to an Info node; INFO-NODE is a string which specifies + the node name, as in `"(emacs)Top"'. The link appears as + `[manual]' in the customization buffer. + + `(info-link INFO-NODE)' + Like `custom-manual' except that the link appears in the + customization buffer with the Info node name. + + `(url-link URL)' + Link to a web page; URL is a string which specifies the URL. + The link appears in the customization buffer as URL. + + You can specify the text to use in the customization buffer by + adding `:tag NAME' after the first element of the LINK-DATA; for + example, `(info-link :tag "foo" "(emacs)Top")' makes a link to the + Emacs manual which appears in the buffer as `foo'. + + An item can have more than one external link; however, most items + have none at all. + +`:load FILE' + Load file FILE (a string) before displaying this customization + item. Loading is done with `load-library', and only if the file is + not already loaded. + +`:require FEATURE' + Require feature FEATURE (a symbol) when installing a value for + this item (an option or a face) that was saved using the + customization feature. This is done by calling `require'. + + The most common reason to use `:require' is when a variable enables + a feature such as a minor mode, and just setting the variable + won't have any effect unless the code which implements the mode is + loaded. + + +File: lispref.info, Node: Group Definitions, Next: Variable Definitions, Prev: Common Keywords, Up: Customization + +19.2 Defining Custom Groups +=========================== + +Each Emacs Lisp package should have one main customization group which +contains all the options, faces and other groups in the package. If the +package has a small number of options and faces, use just one group and +put everything in it. When there are more than twelve or so options and +faces, then you should structure them into subgroups, and put the +subgroups under the package's main customization group. It is OK to +put some of the options and faces in the package's main group alongside +the subgroups. + + The package's main or only group should be a member of one or more of +the standard customization groups. (To display the full list of them, +use `M-x customize'.) Choose one or more of them (but not too many), +and add your group to each of them using the `:group' keyword. + + The way to declare new customization groups is with `defgroup'. + + -- Macro: defgroup group members doc [keyword value]... + Declare GROUP as a customization group containing MEMBERS. Do not + quote the symbol GROUP. The argument DOC specifies the + documentation string for the group. + + The argument MEMBERS is a list specifying an initial set of + customization items to be members of the group. However, most + often MEMBERS is `nil', and you specify the group's members by + using the `:group' keyword when defining those members. + + If you want to specify group members through MEMBERS, each element + should have the form `(NAME WIDGET)'. Here NAME is a symbol, and + WIDGET is a widget type for editing that symbol. Useful widgets + are `custom-variable' for a variable, `custom-face' for a face, + and `custom-group' for a group. + + In addition to the common keywords (*note Common Keywords::), you + can use this keyword in `defgroup': + + `:prefix PREFIX' + If the name of an item in the group starts with PREFIX, then + the tag for that item is constructed (by default) by omitting + PREFIX. + + One group can have any number of prefixes. + + +File: lispref.info, Node: Variable Definitions, Next: Customization Types, Prev: Group Definitions, Up: Customization + +19.3 Defining Customization Variables +===================================== + +Use `defcustom' to declare user-editable variables. + + -- Macro: defcustom option default doc [keyword value]... + Declare OPTION as a customizable user option variable. Do not + quote OPTION. The argument DOC specifies the documentation string + for the variable. + + If OPTION is void, `defcustom' initializes it to DEFAULT. DEFAULT + should be an expression to compute the value; be careful in + writing it, because it can be evaluated on more than one occasion. + + The following additional keywords are defined: + + `:type TYPE' + Use TYPE as the data type for this option. It specifies which + values are legitimate, and how to display the value. *Note + Customization Types::, for more information. + + `:options LIST' + Specify LIST as the list of reasonable values for use in this + option. + + Currently this is meaningful only when the type is `hook'. + In that case, the elements of LIST should be functions that + are useful as elements of the hook value. The user is not + restricted to using only these functions, but they are + offered as convenient alternatives. + + `:version VERSION' + This option specifies that the variable was first introduced, + or its default value was changed, in Emacs version VERSION. + The value VERSION must be a string. For example, + + (defcustom foo-max 34 + "*Maximum number of foo's allowed." + :type 'integer + :group 'foo + :version "20.3") + + `:set SETFUNCTION' + Specify SETFUNCTION as the way to change the value of this + option. The function SETFUNCTION should take two arguments, + a symbol and the new value, and should do whatever is + necessary to update the value properly for this option (which + may not mean simply setting the option as a Lisp variable). + The default for SETFUNCTION is `set-default'. + + `:get GETFUNCTION' + Specify GETFUNCTION as the way to extract the value of this + option. The function GETFUNCTION should take one argument, a + symbol, and should return the "current value" for that symbol + (which need not be the symbol's Lisp value). The default is + `default-value'. + + `:initialize FUNCTION' + FUNCTION should be a function used to initialize the variable + when the `defcustom' is evaluated. It should take two + arguments, the symbol and value. Here are some predefined + functions meant for use in this way: + + `custom-initialize-set' + Use the variable's `:set' function to initialize the + variable, but do not reinitialize it if it is already + non-void. This is the default `:initialize' function. + + `custom-initialize-default' + Like `custom-initialize-set', but use the function + `set-default' to set the variable, instead of the + variable's `:set' function. This is the usual choice + for a variable whose `:set' function enables or disables + a minor mode; with this choice, defining the variable + will not call the minor mode function, but customizing + the variable will do so. + + `custom-initialize-reset' + Always use the `:set' function to initialize the + variable. If the variable is already non-void, reset it + by calling the `:set' function using the current value + (returned by the `:get' method). + + `custom-initialize-changed' + Use the `:set' function to initialize the variable, if + it is already set or has been customized; otherwise, + just use `set-default'. + + The `:require' option is useful for an option that turns on the +operation of a certain feature. Assuming that the package is coded to +check the value of the option, you still need to arrange for the package +to be loaded. You can do that with `:require'. *Note Common +Keywords::. Here is an example, from the library `paren.el': + + (defcustom show-paren-mode nil + "Toggle Show Paren mode...." + :set (lambda (symbol value) + (show-paren-mode (or value 0))) + :initialize 'custom-initialize-default + :type 'boolean + :group 'paren-showing + :require 'paren) + + Internally, `defcustom' uses the symbol property `standard-value' to +record the expression for the default value, and `saved-value' to +record the value saved by the user with the customization buffer. The +`saved-value' property is actually a list whose car is an expression +which evaluates to the value. + + +File: lispref.info, Node: Customization Types, Prev: Variable Definitions, Up: Customization + +19.4 Customization Types +======================== + +When you define a user option with `defcustom', you must specify its +"customization type". That is a Lisp object which describes (1) which +values are legitimate and (2) how to display the value in the +customization buffer for editing. + + You specify the customization type in `defcustom' with the `:type' +keyword. The argument of `:type' is evaluated; since types that vary +at run time are rarely useful, normally you use a quoted constant. For +example: + + (defcustom diff-command "diff" + "*The command to use to run diff." + :type '(string) + :group 'diff) + + In general, a customization type is a list whose first element is a +symbol, one of the customization type names defined in the following +sections. After this symbol come a number of arguments, depending on +the symbol. Between the type symbol and its arguments, you can +optionally write keyword-value pairs (*note Type Keywords::). + + Some of the type symbols do not use any arguments; those are called +"simple types". For a simple type, if you do not use any keyword-value +pairs, you can omit the parentheses around the type symbol. For +example just `string' as a customization type is equivalent to +`(string)'. + +* Menu: + +* Simple Types:: +* Composite Types:: +* Splicing into Lists:: +* Type Keywords:: + + +File: lispref.info, Node: Simple Types, Next: Composite Types, Up: Customization Types + +19.4.1 Simple Types +------------------- + +This section describes all the simple customization types. + +`sexp' + The value may be any Lisp object that can be printed and read + back. You can use `sexp' as a fall-back for any option, if you + don't want to take the time to work out a more specific type to + use. + +`integer' + The value must be an integer, and is represented textually in the + customization buffer. + +`number' + The value must be a number, and is represented textually in the + customization buffer. + +`string' + The value must be a string, and the customization buffer shows + just the contents, with no delimiting `"' characters and no + quoting with `\'. + +`regexp' + Like `string' except that the string must be a valid regular + expression. + +`character' + The value must be a character code. A character code is actually + an integer, but this type shows the value by inserting the + character in the buffer, rather than by showing the number. + +`file' + The value must be a file name, and you can do completion with + `M-'. + +`(file :must-match t)' + The value must be a file name for an existing file, and you can do + completion with `M-'. + +`directory' + The value must be a directory name, and you can do completion with + `M-'. + +`symbol' + The value must be a symbol. It appears in the customization + buffer as the name of the symbol. + +`function' + The value must be either a lambda expression or a function name. + When it is a function name, you can do completion with `M-'. + +`variable' + The value must be a variable name, and you can do completion with + `M-'. + +`face' + The value must be a symbol which is a face name. + +`boolean' + The value is boolean--either `nil' or `t'. Note that by using + `choice' and `const' together (see the next section), you can + specify that the value must be `nil' or `t', but also specify the + text to describe each value in a way that fits the specific + meaning of the alternative. + + +File: lispref.info, Node: Composite Types, Next: Splicing into Lists, Prev: Simple Types, Up: Customization Types + +19.4.2 Composite Types +---------------------- + +When none of the simple types is appropriate, you can use composite +types, which build new types from other types. Here are several ways of +doing that: + +`(restricted-sexp :match-alternatives CRITERIA)' + The value may be any Lisp object that satisfies one of CRITERIA. + CRITERIA should be a list, and each elements should be one of + these possibilities: + + * A predicate--that is, a function of one argument that returns + non-`nil' if the argument fits a certain type. This means + that objects of that type are acceptable. + + * A quoted constant--that is, `'OBJECT'. This means that + OBJECT itself is an acceptable value. + + For example, + + (restricted-sexp :match-alternatives (integerp 't 'nil)) + + allows integers, `t' and `nil' as legitimate values. + + The customization buffer shows all legitimate values using their + read syntax, and the user edits them textually. + +`(cons CAR-TYPE CDR-TYPE)' + The value must be a cons cell, its CAR must fit CAR-TYPE, and its + CDR must fit CDR-TYPE. For example, `(cons string symbol)' is a + customization type which matches values such as `("foo" . foo)'. + + In the customization buffer, the CAR and the CDR are displayed and + edited separately, each according to the type that you specify for + it. + +`(list ELEMENT-TYPES...)' + The value must be a list with exactly as many elements as the + ELEMENT-TYPES you have specified; and each element must fit the + corresponding ELEMENT-TYPE. + + For example, `(list integer string function)' describes a list of + three elements; the first element must be an integer, the second a + string, and the third a function. + + In the customization buffer, the each element is displayed and + edited separately, according to the type specified for it. + +`(vector ELEMENT-TYPES...)' + Like `list' except that the value must be a vector instead of a + list. The elements work the same as in `list'. + +`(choice ALTERNATIVE-TYPES...)' + The value must fit at least one of ALTERNATIVE-TYPES. For + example, `(choice integer string)' allows either an integer or a + string. + + In the customization buffer, the user selects one of the + alternatives using a menu, and can then edit the value in the + usual way for that alternative. + + Normally the strings in this menu are determined automatically + from the choices; however, you can specify different strings for + the menu by including the `:tag' keyword in the alternatives. For + example, if an integer stands for a number of spaces, while a + string is text to use verbatim, you might write the customization + type this way, + + (choice (integer :tag "Number of spaces") + (string :tag "Literal text")) + + so that the menu offers `Number of spaces' and `Literal Text'. + + In any alternative for which `nil' is not a valid value, other than + a `const', you should specify a valid default for that alternative + using the `:value' keyword. *Note Type Keywords::. + +`(const VALUE)' + The value must be VALUE--nothing else is allowed. + + The main use of `const' is inside of `choice'. For example, + `(choice integer (const nil))' allows either an integer or `nil'. + + `:tag' is often used with `const', inside of `choice'. For + example, + + (choice (const :tag "Yes" t) + (const :tag "No" nil) + (const :tag "Ask" foo)) + +`(function-item FUNCTION)' + Like `const', but used for values which are functions. This + displays the documentation string as well as the function name. + The documentation string is either the one you specify with + `:doc', or FUNCTION's own documentation string. + +`(variable-item VARIABLE)' + Like `const', but used for values which are variable names. This + displays the documentation string as well as the variable name. + The documentation string is either the one you specify with + `:doc', or VARIABLE's own documentation string. + +`(set ELEMENTS...)' + The value must be a list and each element of the list must be one + of the ELEMENTS specified. This appears in the customization + buffer as a checklist. + +`(repeat ELEMENT-TYPE)' + The value must be a list and each element of the list must fit the + type ELEMENT-TYPE. This appears in the customization buffer as a + list of elements, with `[INS]' and `[DEL]' buttons for adding more + elements or removing elements. + + +File: lispref.info, Node: Splicing into Lists, Next: Type Keywords, Prev: Composite Types, Up: Customization Types + +19.4.3 Splicing into Lists +-------------------------- + +The `:inline' feature lets you splice a variable number of elements +into the middle of a list or vector. You use it in a `set', `choice' +or `repeat' type which appears among the element-types of a `list' or +`vector'. + + Normally, each of the element-types in a `list' or `vector' +describes one and only one element of the list or vector. Thus, if an +element-type is a `repeat', that specifies a list of unspecified length +which appears as one element. + + But when the element-type uses `:inline', the value it matches is +merged directly into the containing sequence. For example, if it +matches a list with three elements, those become three elements of the +overall sequence. This is analogous to using `,@' in the backquote +construct. + + For example, to specify a list whose first element must be `t' and +whose remaining arguments should be zero or more of `foo' and `bar', +use this customization type: + + (list (const t) (set :inline t foo bar)) + +This matches values such as `(t)', `(t foo)', `(t bar)' and `(t foo +bar)'. + + When the element-type is a `choice', you use `:inline' not in the +`choice' itself, but in (some of) the alternatives of the `choice'. +For example, to match a list which must start with a file name, +followed either by the symbol `t' or two strings, use this +customization type: + + (list file + (choice (const t) + (list :inline t string string))) + +If the user chooses the first alternative in the choice, then the +overall list has two elements and the second element is `t'. If the +user chooses the second alternative, then the overall list has three +elements and the second and third must be strings. + + +File: lispref.info, Node: Type Keywords, Prev: Splicing into Lists, Up: Customization Types + +19.4.4 Type Keywords +-------------------- + +You can specify keyword-argument pairs in a customization type after the +type name symbol. Here are the keywords you can use, and their +meanings: + +`:value DEFAULT' + This is used for a type that appears as an alternative inside of + `choice'; it specifies the default value to use, at first, if and + when the user selects this alternative with the menu in the + customization buffer. + + Of course, if the actual value of the option fits this + alternative, it will appear showing the actual value, not DEFAULT. + + If `nil' is not a valid value for the alternative, then it is + essential to specify a valid default with `:value'. + +`:format FORMAT-STRING' + This string will be inserted in the buffer to represent the value + corresponding to the type. The following `%' escapes are available + for use in FORMAT-STRING: + + `%[BUTTON%]' + Display the text BUTTON marked as a button. The `:action' + attribute specifies what the button will do if the user + invokes it; its value is a function which takes two + arguments--the widget which the button appears in, and the + event. + + There is no way to specify two different buttons with + different actions. + + `%{SAMPLE%}' + Show SAMPLE in a special face specified by `:sample-face'. + + `%v' + Substitute the item's value. How the value is represented + depends on the kind of item, and (for variables) on the + customization type. + + `%d' + Substitute the item's documentation string. + + `%h' + Like `%d', but if the documentation string is more than one + line, add an active field to control whether to show all of + it or just the first line. + + `%t' + Substitute the tag here. You specify the tag with the `:tag' + keyword. + + `%%' + Display a literal `%'. + +`:action ACTION' + Perform ACTION if the user clicks on a button. + +`:button-face FACE' + Use the face FACE (a face name or a list of face names) for button + text displayed with `%[...%]'. + +`:button-prefix PREFIX' +`:button-suffix SUFFIX' + These specify the text to display before and after a button. Each + can be: + + `nil' + No text is inserted. + + a string + The string is inserted literally. + + a symbol + The symbol's value is used. + +`:tag TAG' + Use TAG (a string) as the tag for the value (or part of the value) + that corresponds to this type. + +`:doc DOC' + Use DOC as the documentation string for this value (or part of the + value) that corresponds to this type. In order for this to work, + you must specify a value for `:format', and use `%d' or `%h' in + that value. + + The usual reason to specify a documentation string for a type is to + provide more information about the meanings of alternatives inside + a `:choice' type or the parts of some other composite type. + +`:help-echo MOTION-DOC' + When you move to this item with `widget-forward' or + `widget-backward', it will display the string MOTION-DOC in the + echo area. + +`:match FUNCTION' + Specify how to decide whether a value matches the type. The + corresponding value, FUNCTION, should be a function that accepts + two arguments, a widget and a value; it should return non-`nil' if + the value is acceptable. + + + +File: lispref.info, Node: Loading, Next: Byte Compilation, Prev: Macros, Up: Top + +20 Loading +********** + +Loading a file of Lisp code means bringing its contents into the Lisp +environment in the form of Lisp objects. XEmacs finds and opens the +file, reads the text, evaluates each form, and then closes the file. + + The load functions evaluate all the expressions in a file just as +the `eval-current-buffer' function evaluates all the expressions in a +buffer. The difference is that the load functions read and evaluate +the text in the file as found on disk, not the text in an Emacs buffer. + + The loaded file must contain Lisp expressions, either as source code +or as byte-compiled code. Each form in the file is called a "top-level +form". There is no special format for the forms in a loadable file; +any form in a file may equally well be typed directly into a buffer and +evaluated there. (Indeed, most code is tested this way.) Most often, +the forms are function definitions and variable definitions. + + A file containing Lisp code is often called a "library". Thus, the +"Rmail library" is a file containing code for Rmail mode. Similarly, a +"Lisp library directory" is a directory of files containing Lisp code. + +* Menu: + +* How Programs Do Loading:: The `load' function and others. +* Autoload:: Setting up a function to autoload. +* Repeated Loading:: Precautions about loading a file twice. +* Named Features:: Loading a library if it isn't already loaded. +* Unloading:: How to ``unload'' a library that was loaded. +* Hooks for Loading:: Providing code to be run when + particular libraries are loaded. + + +File: lispref.info, Node: How Programs Do Loading, Next: Autoload, Up: Loading + +20.1 How Programs Do Loading +============================ + +XEmacs Lisp has several interfaces for loading. For example, +`autoload' creates a placeholder object for a function in a file; +trying to call the autoloading function loads the file to get the +function's real definition (*note Autoload::). `require' loads a file +if it isn't already loaded (*note Named Features::). Ultimately, all +these facilities call the `load' function to do the work. + + -- Function: load filename &optional missing-ok nomessage nosuffix + This function finds and opens a file of Lisp code, evaluates all + the forms in it, and closes the file. + + To find the file, `load' first looks for a file named + `FILENAME.elc', that is, for a file whose name is FILENAME with + `.elc' appended. If such a file exists, it is loaded. If there + is no file by that name, then `load' looks for a file named + `FILENAME.el'. If that file exists, it is loaded. Finally, if + neither of those names is found, `load' looks for a file named + FILENAME with nothing appended, and loads it if it exists. (The + `load' function is not clever about looking at FILENAME. In the + perverse case of a file named `foo.el.el', evaluation of `(load + "foo.el")' will indeed find it.) + + If the optional argument NOSUFFIX is non-`nil', then the suffixes + `.elc' and `.el' are not tried. In this case, you must specify + the precise file name you want. + + If FILENAME is a relative file name, such as `foo' or + `baz/foo.bar', `load' searches for the file using the variable + `load-path'. It appends FILENAME to each of the directories + listed in `load-path', and loads the first file it finds whose name + matches. The current default directory is tried only if it is + specified in `load-path', where `nil' stands for the default + directory. `load' tries all three possible suffixes in the first + directory in `load-path', then all three suffixes in the second + directory, and so on. + + If you get a warning that `foo.elc' is older than `foo.el', it + means you should consider recompiling `foo.el'. *Note Byte + Compilation::. + + Messages like `Loading foo...' and `Loading foo...done' appear in + the echo area during loading unless NOMESSAGE is non-`nil'. + + Any unhandled errors while loading a file terminate loading. If + the load was done for the sake of `autoload', any function + definitions made during the loading are undone. + + If `load' can't find the file to load, then normally it signals the + error `file-error' (with `Cannot open load file FILENAME'). But + if MISSING-OK is non-`nil', then `load' just returns `nil'. + + You can use the variable `load-read-function' to specify a function + for `load' to use instead of `read' for reading expressions. See + below. + + `load' returns `t' if the file loads successfully. + + -- User Option: load-path + The value of this variable is a list of directories to search when + loading files with `load'. Each element is a string (which must be + a directory name) or `nil' (which stands for the current working + directory). The value of `load-path' is initialized from the + environment variable `EMACSLOADPATH', if that exists; otherwise its + default value is specified in `emacs/src/paths.h' when XEmacs is + built. + + The syntax of `EMACSLOADPATH' is the same as used for `PATH'; `:' + (or `;', according to the operating system) separates directory + names, and `.' is used for the current default directory. Here is + an example of how to set your `EMACSLOADPATH' variable from a + `csh' `.login' file: + + setenv EMACSLOADPATH .:/user/bil/emacs:/usr/lib/emacs/lisp + + Here is how to set it using `sh': + + export EMACSLOADPATH + EMACSLOADPATH=.:/user/bil/emacs:/usr/local/lib/emacs/lisp + + Here is an example of code you can place in a `.emacs' file to add + several directories to the front of your default `load-path': + + (setq load-path + (append (list nil "/user/bil/emacs" + "/usr/local/lisplib" + "~/emacs") + load-path)) + + In this example, the path searches the current working directory + first, followed then by the `/user/bil/emacs' directory, the + `/usr/local/lisplib' directory, and the `~/emacs' directory, which + are then followed by the standard directories for Lisp code. + + The command line options `-l' or `-load' specify a Lisp library to + load as part of Emacs startup. Since this file might be in the + current directory, Emacs 18 temporarily adds the current directory + to the front of `load-path' so the file can be found there. Newer + Emacs versions also find such files in the current directory, but + without altering `load-path'. + + Dumping Emacs uses a special value of `load-path'. If the value of + `load-path' at the end of dumping is unchanged (that is, still the + same special value), the dumped Emacs switches to the ordinary + `load-path' value when it starts up, as described above. But if + `load-path' has any other value at the end of dumping, that value + is used for execution of the dumped Emacs also. + + Therefore, if you want to change `load-path' temporarily for + loading a few libraries in `site-init.el' or `site-load.el', you + should bind `load-path' locally with `let' around the calls to + `load'. + + -- Function: locate-file filename path-list &optional suffixes mode + This function searches for a file in the same way that `load' does, + and returns the file found (if any). (In fact, `load' uses this + function to search through `load-path'.) It searches for FILENAME + through PATH-LIST, expanded by one of the optional SUFFIXES + (string of suffixes separated by `:'s), checking for access MODE + (0|1|2|4 = exists|executable|writable|readable), default readable. + + `locate-file' keeps hash tables of the directories it searches + through, in order to speed things up. It tries valiantly to not + get confused in the face of a changing and unpredictable + environment, but can occasionally get tripped up. In this case, + you will have to call `locate-file-clear-hashing' to get it back + on track. See that function for details. + + -- Function: locate-file-clear-hashing path + This function clears the hash records for the specified list of + directories. `locate-file' uses a hashing scheme to speed lookup, + and will correctly track the following environmental changes: + + * changes of any sort to the list of directories to be searched. + + * addition and deletion of non-shadowing files (see below) from + the directories in the list. + + * byte-compilation of a .el file into a .elc file. + + `locate-file' will primarily get confused if you add a file that + shadows (i.e. has the same name as) another file further down in + the directory list. In this case, you must call + `locate-file-clear-hashing'. + + -- Variable: load-in-progress + This variable is non-`nil' if Emacs is in the process of loading a + file, and it is `nil' otherwise. + + -- Variable: load-read-function + This variable specifies an alternate expression-reading function + for `load' and `eval-region' to use instead of `read'. The + function should accept one argument, just as `read' does. + + Normally, the variable's value is `nil', which means those + functions should use `read'. + + -- User Option: load-warn-when-source-newer + This variable specifies whether `load' should check whether the + source is newer than the binary. If this variable is true, then + when a `.elc' file is being loaded and the corresponding `.el' is + newer, a warning message will be printed. The default is `nil', + but it is bound to `t' during the initial loadup. + + -- User Option: load-warn-when-source-only + This variable specifies whether `load' should warn when loading a + `.el' file instead of an `.elc'. If this variable is true, then + when `load' is called with a filename without an extension, and + the `.elc' version doesn't exist but the `.el' version does, then + a message will be printed. If an explicit extension is passed to + `load', no warning will be printed. The default is `nil', but it + is bound to `t' during the initial loadup. + + -- User Option: load-ignore-elc-files + This variable specifies whether `load' should ignore `.elc' files + when a suffix is not given. This is normally used only to + bootstrap the `.elc' files when building XEmacs, when you use the + command `make all-elc'. (This forces the `.el' versions to be + loaded in the process of compiling those same files, so that + existing out-of-date `.elc' files do not make it mess things up.) + + To learn how `load' is used to build XEmacs, see *Note Building +XEmacs::. + diff -u -r -N xemacs-21.4.18/info/lispref.info-3 xemacs-21.4.19/info/lispref.info-3 --- xemacs-21.4.18/info/lispref.info-3 1969-12-31 19:00:00.000000000 -0500 +++ xemacs-21.4.19/info/lispref.info-3 2006-01-28 18:57:51.000000000 -0500 @@ -0,0 +1,7224 @@ +This is ../info/lispref.info, produced by makeinfo version 4.8 from +lispref/lispref.texi. + +INFO-DIR-SECTION XEmacs Editor +START-INFO-DIR-ENTRY +* Lispref: (lispref). XEmacs Lisp Reference Manual. +END-INFO-DIR-ENTRY + + Edition History: + + GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU +Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid +Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994 +XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995 +GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp +Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp +Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp +Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May, +November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998 + + Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software +Foundation, Inc. Copyright (C) 1994, 1995 Sun Microsystems, Inc. +Copyright (C) 1995, 1996 Ben Wing. + + Permission is granted to make and distribute verbatim copies of this +manual provided the copyright notice and this permission notice are +preserved on all copies. + + Permission is granted to copy and distribute modified versions of +this manual under the conditions for verbatim copying, provided that the +entire resulting derived work is distributed under the terms of a +permission notice identical to this one. + + Permission is granted to copy and distribute translations of this +manual into another language, under the above conditions for modified +versions, except that this permission notice may be stated in a +translation approved by the Foundation. + + Permission is granted to copy and distribute modified versions of +this manual under the conditions for verbatim copying, provided also +that the section entitled "GNU General Public License" is included +exactly as in the original, and provided that the entire resulting +derived work is distributed under the terms of a permission notice +identical to this one. + + Permission is granted to copy and distribute translations of this +manual into another language, under the above conditions for modified +versions, except that the section entitled "GNU General Public License" +may be included in a translation approved by the Free Software +Foundation instead of in the original English. + + +File: lispref.info, Node: Autoload, Next: Repeated Loading, Prev: How Programs Do Loading, Up: Loading + +20.2 Autoload +============= + +The "autoload" facility allows you to make a function or macro known in +Lisp, but put off loading the file that defines it. The first call to +the function automatically reads the proper file to install the real +definition and other associated code, then runs the real definition as +if it had been loaded all along. + + There are two ways to set up an autoloaded function: by calling +`autoload', and by writing a special "magic" comment in the source +before the real definition. `autoload' is the low-level primitive for +autoloading; any Lisp program can call `autoload' at any time. Magic +comments do nothing on their own; they serve as a guide for the command +`update-file-autoloads', which constructs calls to `autoload' and +arranges to execute them when Emacs is built. Magic comments are the +most convenient way to make a function autoload, but only for packages +installed along with Emacs. + + -- Function: autoload function filename &optional docstring + interactive type + This function defines the function (or macro) named FUNCTION so as + to load automatically from FILENAME. The string FILENAME + specifies the file to load to get the real definition of FUNCTION. + + The argument DOCSTRING is the documentation string for the + function. Normally, this is identical to the documentation string + in the function definition itself. Specifying the documentation + string in the call to `autoload' makes it possible to look at the + documentation without loading the function's real definition. + + If INTERACTIVE is non-`nil', then the function can be called + interactively. This lets completion in `M-x' work without loading + the function's real definition. The complete interactive + specification need not be given here; it's not needed unless the + user actually calls FUNCTION, and when that happens, it's time to + load the real definition. + + You can autoload macros and keymaps as well as ordinary functions. + Specify TYPE as `macro' if FUNCTION is really a macro. Specify + TYPE as `keymap' if FUNCTION is really a keymap. Various parts of + Emacs need to know this information without loading the real + definition. + + An autoloaded keymap loads automatically during key lookup when a + prefix key's binding is the symbol FUNCTION. Autoloading does not + occur for other kinds of access to the keymap. In particular, it + does not happen when a Lisp program gets the keymap from the value + of a variable and calls `define-key'; not even if the variable + name is the same symbol FUNCTION. + + If FUNCTION already has a non-void function definition that is not + an autoload object, `autoload' does nothing and returns `nil'. If + the function cell of FUNCTION is void, or is already an autoload + object, then it is defined as an autoload object like this: + + (autoload FILENAME DOCSTRING INTERACTIVE TYPE) + + For example, + + (symbol-function 'run-prolog) + => (autoload "prolog" 169681 t nil) + + In this case, `"prolog"' is the name of the file to load, 169681 + refers to the documentation string in the `DOC' file (*note + Documentation Basics::), `t' means the function is interactive, + and `nil' that it is not a macro or a keymap. + + The autoloaded file usually contains other definitions and may +require or provide one or more features. If the file is not completely +loaded (due to an error in the evaluation of its contents), any function +definitions or `provide' calls that occurred during the load are +undone. This is to ensure that the next attempt to call any function +autoloading from this file will try again to load the file. If not for +this, then some of the functions in the file might appear defined, but +they might fail to work properly for the lack of certain subroutines +defined later in the file and not loaded successfully. + + XEmacs as distributed comes with many autoloaded functions. The +calls to `autoload' are in the file `loaddefs.el'. There is a +convenient way of updating them automatically. + + If the autoloaded file fails to define the desired Lisp function or +macro, then an error is signaled with data `"Autoloading failed to +define function FUNCTION-NAME"'. + + A magic autoload comment looks like `;;;###autoload', on a line by +itself, just before the real definition of the function in its +autoloadable source file. The command `M-x update-file-autoloads' +writes a corresponding `autoload' call into `loaddefs.el'. Building +Emacs loads `loaddefs.el' and thus calls `autoload'. `M-x +update-directory-autoloads' is even more powerful; it updates autoloads +for all files in the current directory. + + The same magic comment can copy any kind of form into `loaddefs.el'. +If the form following the magic comment is not a function definition, +it is copied verbatim. You can also use a magic comment to execute a +form at build time _without_ executing it when the file itself is +loaded. To do this, write the form "on the same line" as the magic +comment. Since it is in a comment, it does nothing when you load the +source file; but `update-file-autoloads' copies it to `loaddefs.el', +where it is executed while building Emacs. + + The following example shows how `doctor' is prepared for autoloading +with a magic comment: + + ;;;###autoload + (defun doctor () + "Switch to *doctor* buffer and start giving psychotherapy." + (interactive) + (switch-to-buffer "*doctor*") + (doctor-mode)) + +Here's what that produces in `loaddefs.el': + + (autoload 'doctor "doctor" + "\ + Switch to *doctor* buffer and start giving psychotherapy." + t) + +The backslash and newline immediately following the double-quote are a +convention used only in the preloaded Lisp files such as `loaddefs.el'; +they tell `make-docfile' to put the documentation string in the `DOC' +file. *Note Building XEmacs::. + + +File: lispref.info, Node: Repeated Loading, Next: Named Features, Prev: Autoload, Up: Loading + +20.3 Repeated Loading +===================== + +You may load one file more than once in an Emacs session. For example, +after you have rewritten and reinstalled a function definition by +editing it in a buffer, you may wish to return to the original version; +you can do this by reloading the file it came from. + + When you load or reload files, bear in mind that the `load' and +`load-library' functions automatically load a byte-compiled file rather +than a non-compiled file of similar name. If you rewrite a file that +you intend to save and reinstall, remember to byte-compile it if +necessary; otherwise you may find yourself inadvertently reloading the +older, byte-compiled file instead of your newer, non-compiled file! + + When writing the forms in a Lisp library file, keep in mind that the +file might be loaded more than once. For example, the choice of +`defvar' vs. `defconst' for defining a variable depends on whether it +is desirable to reinitialize the variable if the library is reloaded: +`defconst' does so, and `defvar' does not. (*Note Defining +Variables::.) + + The simplest way to add an element to an alist is like this: + + (setq minor-mode-alist + (cons '(leif-mode " Leif") minor-mode-alist)) + +But this would add multiple elements if the library is reloaded. To +avoid the problem, write this: + + (or (assq 'leif-mode minor-mode-alist) + (setq minor-mode-alist + (cons '(leif-mode " Leif") minor-mode-alist))) + + To add an element to a list just once, use `add-to-list' (*note +Setting Variables::). + + Occasionally you will want to test explicitly whether a library has +already been loaded. Here's one way to test, in a library, whether it +has been loaded before: + + (defvar foo-was-loaded) + + (if (not (boundp 'foo-was-loaded)) + EXECUTE-FIRST-TIME-ONLY) + + (setq foo-was-loaded t) + +If the library uses `provide' to provide a named feature, you can use +`featurep' to test whether the library has been loaded. *Note Named +Features::. + + +File: lispref.info, Node: Named Features, Next: Unloading, Prev: Repeated Loading, Up: Loading + +20.4 Features +============= + +`provide' and `require' are an alternative to `autoload' for loading +files automatically. They work in terms of named "features". +Autoloading is triggered by calling a specific function, but a feature +is loaded the first time another program asks for it by name. + + A feature name is a symbol that stands for a collection of functions, +variables, etc. The file that defines them should "provide" the +feature. Another program that uses them may ensure they are defined by +"requiring" the feature. This loads the file of definitions if it +hasn't been loaded already. + + To require the presence of a feature, call `require' with the +feature name as argument. `require' looks in the global variable +`features' to see whether the desired feature has been provided +already. If not, it loads the feature from the appropriate file. This +file should call `provide' at the top level to add the feature to +`features'; if it fails to do so, `require' signals an error. + + Features are normally named after the files that provide them, so +that `require' need not be given the file name. + + For example, in `emacs/lisp/prolog.el', the definition for +`run-prolog' includes the following code: + + (defun run-prolog () + "Run an inferior Prolog process, input and output via buffer *prolog*." + (interactive) + (require 'comint) + (switch-to-buffer (make-comint "prolog" prolog-program-name)) + (inferior-prolog-mode)) + +The expression `(require 'comint)' loads the file `comint.el' if it has +not yet been loaded. This ensures that `make-comint' is defined. + + The `comint.el' file contains the following top-level expression: + + (provide 'comint) + +This adds `comint' to the global `features' list, so that `(require +'comint)' will henceforth know that nothing needs to be done. + + When `require' is used at top level in a file, it takes effect when +you byte-compile that file (*note Byte Compilation::) as well as when +you load it. This is in case the required package contains macros that +the byte compiler must know about. + + Although top-level calls to `require' are evaluated during byte +compilation, `provide' calls are not. Therefore, you can ensure that a +file of definitions is loaded before it is byte-compiled by including a +`provide' followed by a `require' for the same feature, as in the +following example. + + (provide 'my-feature) ; Ignored by byte compiler, + ; evaluated by `load'. + (require 'my-feature) ; Evaluated by byte compiler. + +The compiler ignores the `provide', then processes the `require' by +loading the file in question. Loading the file does execute the +`provide' call, so the subsequent `require' call does nothing while +loading. + + -- Function: provide feature + This function announces that FEATURE is now loaded, or being + loaded, into the current XEmacs session. This means that the + facilities associated with FEATURE are or will be available for + other Lisp programs. + + The direct effect of calling `provide' is to add FEATURE to the + front of the list `features' if it is not already in the list. + The argument FEATURE must be a symbol. `provide' returns FEATURE. + + features + => (bar bish) + + (provide 'foo) + => foo + features + => (foo bar bish) + + When a file is loaded to satisfy an autoload, and it stops due to + an error in the evaluating its contents, any function definitions + or `provide' calls that occurred during the load are undone. + *Note Autoload::. + + -- Function: require feature &optional filename + This function checks whether FEATURE is present in the current + XEmacs session (using `(featurep FEATURE)'; see below). If it is + not, then `require' loads FILENAME with `load'. If FILENAME is + not supplied, then the name of the symbol FEATURE is used as the + file name to load. + + If loading the file fails to provide FEATURE, `require' signals an + error, `Required feature FEATURE was not provided'. + + -- Function: featurep fexp + This function returns `t' if feature FEXP is present in this + Emacs. Use this to conditionalize execution of lisp code based on + the presence or absence of emacs or environment extensions. + + FEXP can be a symbol, a number, or a list. + + If FEXP is a symbol, it is looked up in the `features' variable, + and `t' is returned if it is found, `nil' otherwise. + + If FEXP is a number, the function returns `t' if this Emacs has an + equal or greater number than FEXP, `nil' otherwise. Note that + minor Emacs version is expected to be 2 decimal places wide, so + `(featurep 20.4)' will return `nil' on XEmacs 20.4--you must write + `(featurep 20.04)', unless you wish to match for XEmacs 20.40. + + If FEXP is a list whose car is the symbol `and', the function + returns `t' if all the features in its cdr are present, `nil' + otherwise. + + If FEXP is a list whose car is the symbol `or', the function + returns `t' if any the features in its cdr are present, `nil' + otherwise. + + If FEXP is a list whose car is the symbol `not', the function + returns `t' if the feature is not present, `nil' otherwise. + + Examples: + + (featurep 'xemacs) + => ; t on XEmacs. + + (featurep '(and xemacs gnus)) + => ; t on XEmacs with Gnus loaded. + + (featurep '(or tty-frames (and emacs 19.30))) + => ; t if this Emacs supports TTY frames. + + (featurep '(or (and xemacs 19.15) (and emacs 19.34))) + => ; t on XEmacs 19.15 and later, or on + ; FSF Emacs 19.34 and later. + + *Please note:* The advanced arguments of this function (anything + other than a symbol) are not yet supported by FSF Emacs. If you + feel they are useful for supporting multiple Emacs variants, lobby + Richard Stallman at `'. + + -- Variable: features + The value of this variable is a list of symbols that are the + features loaded in the current XEmacs session. Each symbol was + put in this list with a call to `provide'. The order of the + elements in the `features' list is not significant. + + +File: lispref.info, Node: Unloading, Next: Hooks for Loading, Prev: Named Features, Up: Loading + +20.5 Unloading +============== + +You can discard the functions and variables loaded by a library to +reclaim memory for other Lisp objects. To do this, use the function +`unload-feature': + + -- Command: unload-feature feature &optional force + This command unloads the library that provided feature FEATURE. + It undefines all functions, macros, and variables defined in that + library with `defconst', `defvar', `defun', `defmacro', + `defsubst', `define-function' and `defalias'. It then restores + any autoloads formerly associated with those symbols. (Loading + saves these in the `autoload' property of the symbol.) + + Ordinarily, `unload-feature' refuses to unload a library on which + other loaded libraries depend. (A library A depends on library B + if A contains a `require' for B.) If the optional argument FORCE + is non-`nil', dependencies are ignored and you can unload any + library. + + The `unload-feature' function is written in Lisp; its actions are +based on the variable `load-history'. + + -- Variable: load-history + This variable's value is an alist connecting library names with the + names of functions and variables they define, the features they + provide, and the features they require. + + Each element is a list and describes one library. The CAR of the + list is the name of the library, as a string. The rest of the + list is composed of these kinds of objects: + + * Symbols that were defined by this library. + + * Lists of the form `(require . FEATURE)' indicating features + that were required. + + * Lists of the form `(provide . FEATURE)' indicating features + that were provided. + + The value of `load-history' may have one element whose CAR is + `nil'. This element describes definitions made with `eval-buffer' + on a buffer that is not visiting a file. + + The command `eval-region' updates `load-history', but does so by +adding the symbols defined to the element for the file being visited, +rather than replacing that element. + + +File: lispref.info, Node: Hooks for Loading, Prev: Unloading, Up: Loading + +20.6 Hooks for Loading +====================== + + -- Variable: after-load-alist + An alist of expressions to evaluate if and when particular + libraries are loaded. Each element looks like this: + + (FILENAME FORMS...) + + When `load' is run and the file-name argument is FILENAME, the + FORMS in the corresponding element are executed at the end of + loading. + + FILENAME must match exactly! Normally FILENAME is the name of a + library, with no directory specified, since that is how `load' is + normally called. An error in FORMS does not undo the load, but + does prevent execution of the rest of the FORMS. + + + +File: lispref.info, Node: Byte Compilation, Next: Debugging, Prev: Loading, Up: Top + +21 Byte Compilation +******************* + +XEmacs Lisp has a "compiler" that translates functions written in Lisp +into a special representation called "byte-code" that can be executed +more efficiently. The compiler replaces Lisp function definitions with +byte-code. When a byte-coded function is called, its definition is +evaluated by the "byte-code interpreter". + + Because the byte-compiled code is evaluated by the byte-code +interpreter, instead of being executed directly by the machine's +hardware (as true compiled code is), byte-code is completely +transportable from machine to machine without recompilation. It is not, +however, as fast as true compiled code. + + In general, any version of Emacs can run byte-compiled code produced +by recent earlier versions of Emacs, but the reverse is not true. In +particular, if you compile a program with XEmacs 20, the compiled code +may not run in earlier versions. + + The first time a compiled-function object is executed, the byte-code +instructions are validated and the byte-code is further optimized. An +`invalid-byte-code' error is signaled if the byte-code is invalid, for +example if it contains invalid opcodes. This usually means a bug in +the byte compiler. + + *Note Compilation Errors::, for how to investigate errors occurring +in byte compilation. + +* Menu: + +* Speed of Byte-Code:: An example of speedup from byte compilation. +* Compilation Functions:: Byte compilation functions. +* Compilation Options:: Controlling the byte compiler's behavior. +* Docs and Compilation:: Dynamic loading of documentation strings. +* Dynamic Loading:: Dynamic loading of individual functions. +* Eval During Compile:: Code to be evaluated when you compile. +* Compiled-Function Objects:: The data type used for byte-compiled functions. +* Disassembly:: Disassembling byte-code; how to read byte-code. +* Different Behavior:: When compiled code gives different results. + + +File: lispref.info, Node: Speed of Byte-Code, Next: Compilation Functions, Up: Byte Compilation + +21.1 Performance of Byte-Compiled Code +====================================== + +A byte-compiled function is not as efficient as a primitive function +written in C, but runs much faster than the version written in Lisp. +Here is an example: + + (defun silly-loop (n) + "Return time before and after N iterations of a loop." + (let ((t1 (current-time-string))) + (while (> (setq n (1- n)) + 0)) + (list t1 (current-time-string)))) + => silly-loop + + (silly-loop 5000000) + => ("Mon Sep 14 15:51:49 1998" + "Mon Sep 14 15:52:07 1998") ; 18 seconds + + (byte-compile 'silly-loop) + => # + + (silly-loop 5000000) + => ("Mon Sep 14 15:53:43 1998" + "Mon Sep 14 15:53:49 1998") ; 6 seconds + + In this example, the interpreted code required 18 seconds to run, +whereas the byte-compiled code required 6 seconds. These results are +representative, but actual results will vary greatly. + + +File: lispref.info, Node: Compilation Functions, Next: Compilation Options, Prev: Speed of Byte-Code, Up: Byte Compilation + +21.2 The Compilation Functions +============================== + +You can byte-compile an individual function or macro definition with +the `byte-compile' function. You can compile a whole file with +`byte-compile-file', or several files with `byte-recompile-directory' +or `batch-byte-compile'. + + When you run the byte compiler, you may get warnings in a buffer +called `*Compile-Log*'. These report things in your program that +suggest a problem but are not necessarily erroneous. + + Be careful when byte-compiling code that uses macros. Macro calls +are expanded when they are compiled, so the macros must already be +defined for proper compilation. For more details, see *Note Compiling +Macros::. + + Normally, compiling a file does not evaluate the file's contents or +load the file. But it does execute any `require' calls at top level in +the file. One way to ensure that necessary macro definitions are +available during compilation is to `require' the file that defines them +(*note Named Features::). To avoid loading the macro definition files +when someone _runs_ the compiled program, write `eval-when-compile' +around the `require' calls (*note Eval During Compile::). + + -- Function: byte-compile symbol + This function byte-compiles the function definition of SYMBOL, + replacing the previous definition with the compiled one. The + function definition of SYMBOL must be the actual code for the + function; i.e., the compiler does not follow indirection to + another symbol. `byte-compile' returns the new, compiled + definition of SYMBOL. + + If SYMBOL's definition is a compiled-function object, + `byte-compile' does nothing and returns `nil'. Lisp records only + one function definition for any symbol, and if that is already + compiled, non-compiled code is not available anywhere. So there + is no way to "compile the same definition again." + + (defun factorial (integer) + "Compute factorial of INTEGER." + (if (= 1 integer) 1 + (* integer (factorial (1- integer))))) + => factorial + + (byte-compile 'factorial) + => # + + The result is a compiled-function object. The string it contains + is the actual byte-code; each character in it is an instruction or + an operand of an instruction. The vector contains all the + constants, variable names and function names used by the function, + except for certain primitives that are coded as special + instructions. + + -- Command: compile-defun &optional arg + This command reads the defun containing point, compiles it, and + evaluates the result. If you use this on a defun that is actually + a function definition, the effect is to install a compiled version + of that function. + + If ARG is non-`nil', the result is inserted in the current buffer + after the form; otherwise, it is printed in the minibuffer. + + -- Command: byte-compile-file filename &optional load + This function compiles a file of Lisp code named FILENAME into a + file of byte-code. The output file's name is made by appending + `c' to the end of FILENAME. + + If `load' is non-`nil', the file is loaded after having been + compiled. + + Compilation works by reading the input file one form at a time. + If it is a definition of a function or macro, the compiled + function or macro definition is written out. Other forms are + batched together, then each batch is compiled, and written so that + its compiled code will be executed when the file is read. All + comments are discarded when the input file is read. + + This command returns `t'. When called interactively, it prompts + for the file name. + + % ls -l push* + -rw-r--r-- 1 lewis 791 Oct 5 20:31 push.el + + (byte-compile-file "~/emacs/push.el") + => t + + % ls -l push* + -rw-r--r-- 1 lewis 791 Oct 5 20:31 push.el + -rw-r--r-- 1 lewis 638 Oct 8 20:25 push.elc + + -- Command: byte-recompile-directory directory &optional flag + norecursion force + This function recompiles every `.el' file in DIRECTORY that needs + recompilation. A file needs recompilation if a `.elc' file exists + but is older than the `.el' file. + + Files in subdirectories of DIRECTORY are also processed unless + optional argument NORECURSION is non-`nil'. + + When a `.el' file has no corresponding `.elc' file, then FLAG says + what to do. If it is `nil', these files are ignored. If it is + non-`nil', the user is asked whether to compile each such file. + + If the fourth optional argument FORCE is non-`nil', recompile + every `.el' file that already has a `.elc' file. + + The return value of this command is unpredictable. + + -- Function: batch-byte-compile + This function runs `byte-compile-file' on files specified on the + command line. This function must be used only in a batch + execution of Emacs, as it kills Emacs on completion. An error in + one file does not prevent processing of subsequent files. (The + file that gets the error will not, of course, produce any compiled + code.) + + % xemacs -batch -f batch-byte-compile *.el + + -- Function: batch-byte-recompile-directory + This function is similar to `batch-byte-compile' but runs the + command `byte-recompile-directory' on the files remaining on the + command line. + + -- Variable: byte-recompile-directory-ignore-errors-p + When non-`nil', `byte-recompile-directory' will continue compiling + even when an error occurs in a file. Default: `nil', but bound to + `t' by `batch-byte-recompile-directory'. + + -- Variable: byte-recompile-directory-recursively + When non-`nil', `byte-recompile-directory' will recurse on + subdirectories. Default: `t'. + + -- Function: byte-code instructions constants stack-depth + This function actually interprets byte-code. Don't call this + function yourself. Only the byte compiler knows how to generate + valid calls to this function. + + In newer Emacs versions (19 and up), byte code is usually executed + as part of a compiled-function object, and only rarely due to an + explicit call to `byte-code'. A byte-compiled function was once + actually defined with a body that calls `byte-code', but in recent + versions of Emacs `byte-code' is only used to run isolated + fragments of lisp code without an associated argument list. + + +File: lispref.info, Node: Compilation Options, Next: Docs and Compilation, Prev: Compilation Functions, Up: Byte Compilation + +21.3 Options for the Byte Compiler +================================== + +Warning: this node is a quick draft based on docstrings. There may be +inaccuracies, as the docstrings occasionally disagree with each other. +This has not been checked yet. + + The byte compiler and optimizer are controlled by the following +variables. The `byte-compiler-options' macro described below provides +a convenient way to set most of them on a file-by-file basis. + + -- Variable: emacs-lisp-file-regexp + Regexp which matches Emacs Lisp source files. You may want to + redefine `byte-compile-dest-file' if you change this. Default: + `"\\.el$"'. + + -- Function: byte-compile-dest-file filename + Convert an Emacs Lisp source file name to a compiled file name. + This function may be redefined by the user, if necessary, for + compatibility with `emacs-lisp-file-regexp'. + + -- Variable: byte-compile-verbose + When non-`nil', print messages describing progress of + byte-compiler. Default: `t' if interactive on a not-too-slow + terminal (see `search-slow-speed'), otherwise `nil'. + + -- Variable: byte-optimize + Level of optimization in the byte compiler. + + `nil' + Do no optimization. + + `t' + Do all optimizations. + + `source' + Do optimizations manipulating the source code only. + + `byte' + Do optimizations manipulating the byte code (actually, LAP + code) only. + Default: `t'. + + -- Variable: byte-compile-delete-errors + When non-`nil', the optimizer may delete forms that may signal an + error if that is the only change in the function's behavior. This + includes variable references and calls to functions such as `car'. + Default: `t'. + + -- Variable: byte-optimize-log nil + When non-`nil', the byte-compiler logs optimizations into + `*Compile-Log*'. + + `nil' + Log no optimization. + + `t' + Log all optimizations. + + `source' + Log optimizations manipulating the source code only. + + `byte' + Log optimizations manipulating the byte code (actually, LAP + code) only. + Default: `nil'. + + -- Variable: byte-compile-error-on-warn + When non-`nil', the byte-compiler reports warnings with `error'. + Default: `nil'. + + -- Variable: byte-compile-default-warnings + The warnings used when `byte-compile-warnings' is `t'. Called + `byte-compile-warning-types' in GNU Emacs. Default: `(redefine + callargs subr-callargs free-vars unresolved unused-vars obsolete)'. + + -- Variable: byte-compile-warnings + List of warnings that the compiler should issue (`t' for the + default set). Elements of the list may be: + + `free-vars' + References to variables not in the current lexical scope. + + `unused-vars' + References to non-global variables bound but not referenced. + + `unresolved' + Calls to unknown functions. + + `callargs' + Lambda calls with args that don't match the definition. + + `subr-callargs' + Calls to subrs with args that don't match the definition. + + `redefine' + Function cell redefined from a macro to a lambda or vice + versa, or redefined to take a different number of arguments. + + `obsolete' + Use of an obsolete function or variable. + + `pedantic' + Warn of use of compatible symbols. + + The default set is specified by `byte-compile-default-warnings' and + normally encompasses all possible warnings. + + See also the macro `byte-compiler-options'. Default: `t'. + + The compiler can generate a call graph, which gives information about +which functions call which functions. + + -- Variable: byte-compile-generate-call-tree + When non-`nil', the compiler generates a call graph. This records + functions that were called and from where. If the value is `t', + compilation displays the call graph when it finishes. If the + value is neither `t' nor `nil', compilation asks you whether to + display the graph. + + The call tree only lists functions called, not macros used. Those + functions which the byte-code interpreter knows about directly + (`eq', `cons', etc.) are not reported. + + The call tree also lists those functions which are not known to be + called (that is, to which no calls have been compiled). Functions + which can be invoked interactively are excluded from this list. + Default: `nil'. + + -- Variable: byte-compile-call-tree nil + Alist of functions and their call tree, used internally. Each + element takes the form + + (FUNCTION CALLERS CALLS) + + where CALLERS is a list of functions that call FUNCTION, and CALLS + is a list of functions for which calls were generated while + compiling FUNCTION. + + -- Variable: byte-compile-call-tree-sort + When non-`nil', sort the call tree. The values `name', `callers', + `calls', and `calls+callers' specify different fields to sort + on.") Default: `name'. + + `byte-compile-overwrite-file' controls treatment of existing +compiled files. + + -- Variable: byte-compile-overwrite-file + When non-`nil', do not preserve backups of `.elc's. Precisely, if + `nil', old `.elc' files are deleted before the new one is saved, + and `.elc' files will have the same modes as the corresponding + `.el' file. Otherwise, existing `.elc' files will simply be + overwritten, and the existing modes will not be changed. If this + variable is `nil', then an `.elc' file which is a symbolic link + will be turned into a normal file, instead of the file which the + link points to being overwritten. Default: `t'. + + Variables controlling recompiling directories are described elsewhere +*Note Compilation Functions::. They are +`byte-recompile-directory-ignore-errors-p' and +`byte-recompile-directory-recursively'. + + The dynamic loading features are described elsewhere. These are +controlled by the variables `byte-compile-dynamic' (*note Dynamic +Loading::) and `byte-compile-dynamic-docstrings' (*note Docs and +Compilation::). + + The byte compiler is a relatively recent development, and has evolved +significantly over the period covering Emacs versions 19 and 20. The +following variables control use of newer functionality by the byte +compiler. These are rarely needed since the release of XEmacs 21. + + Another set of compatibility issues arises between Mule and non-Mule +XEmacsen; there are no known compatibility issues specific to the byte +compiler. There are also compatibility issues between XEmacs and GNU +Emacs's versions of the byte compiler. While almost all of the byte +codes are the same, and code compiled by one version often runs +perfectly well on the other, this is very dangerous, and can result in +crashes or data loss. Always recompile your Lisp when moving between +XEmacs and GNU Emacs. + + -- Variable: byte-compile-single-version nil + When non-`nil', the choice of emacs version (v19 or v20) byte-codes + will be hard-coded into bytecomp when it compiles itself. If the + compiler itself is compiled with optimization, this causes a + speedup. Default: `nil'. + + -- Variable: byte-compile-emacs19-compatibility + When non-`nil' generate output that can run in Emacs 19. Default: + `nil' when Emacs version is 20 or above, otherwise `t'. + + -- Variable: byte-compile-print-gensym + When non-`nil', the compiler may generate code that creates unique + symbols at run-time. This is achieved by printing uninterned + symbols using the `#:' notation, so that they will be read + uninterned when run. + + With this feature, code that uses uninterned symbols in macros will + not be runnable under pre-21.0 XEmacsen. + + Default: When `byte-compile-emacs19-compatibility' is non-nil, this + variable is ignored and considered to be `nil'. Otherwise `t'. + + -- Variable: byte-compile-new-bytecodes + This is completely ignored. For backwards compatibility. + + -- Function: byte-compiler-options &rest args + Set some compilation-parameters for this file. This will affect + only the file in which it appears; this does nothing when + evaluated, or when loaded from a `.el' file. + + Each argument to this macro must be a list of a key and a value. + (#### Need to check whether the newer variables are settable here.) + + Keys: Values: Corresponding variable: + + verbose t, nil byte-compile-verbose + optimize t, nil, source, byte byte-optimize + warnings list of warnings byte-compile-warnings + file-format emacs19, emacs20 byte-compile-emacs19-compatibility + + The value specified with the `warnings'option must be a list, + containing some subset of the following flags: + + free-vars references to variables not in the current lexical scope. + unused-vars references to non-global variables bound but not referenced. + unresolved calls to unknown functions. + callargs lambda calls with args that don't match the definition. + redefine function cell redefined from a macro to a lambda or vice + versa, or redefined to take a different number of arguments. + + If the first element if the list is `+' or ``' then the specified + elements are added to or removed from the current set of warnings, + instead of the entire set of warnings being overwritten. (#### + Need to check whether the newer warnings are settable here.) + + For example, something like this might appear at the top of a + source file: + + (byte-compiler-options + (optimize t) + (warnings (- callargs)) ; Don't warn about arglist mismatch + (warnings (+ unused-vars)) ; Do warn about unused bindings + (file-format emacs19)) + + +File: lispref.info, Node: Docs and Compilation, Next: Dynamic Loading, Prev: Compilation Options, Up: Byte Compilation + +21.4 Documentation Strings and Compilation +========================================== + +Functions and variables loaded from a byte-compiled file access their +documentation strings dynamically from the file whenever needed. This +saves space within Emacs, and makes loading faster because the +documentation strings themselves need not be processed while loading the +file. Actual access to the documentation strings becomes slower as a +result, but normally not enough to bother users. + + Dynamic access to documentation strings does have drawbacks: + + * If you delete or move the compiled file after loading it, Emacs + can no longer access the documentation strings for the functions + and variables in the file. + + * If you alter the compiled file (such as by compiling a new + version), then further access to documentation strings in this + file will give nonsense results. + + If your site installs Emacs following the usual procedures, these +problems will never normally occur. Installing a new version uses a new +directory with a different name; as long as the old version remains +installed, its files will remain unmodified in the places where they are +expected to be. + + However, if you have built Emacs yourself and use it from the +directory where you built it, you will experience this problem +occasionally if you edit and recompile Lisp files. When it happens, you +can cure the problem by reloading the file after recompiling it. + + Versions of Emacs up to and including XEmacs 19.14 and FSF Emacs +19.28 do not support the dynamic docstrings feature, and so will not be +able to load bytecode created by more recent Emacs versions. You can +turn off the dynamic docstring feature by setting +`byte-compile-dynamic-docstrings' to `nil'. Once this is done, you can +compile files that will load into older Emacs versions. You can do +this globally, or for one source file by specifying a file-local +binding for the variable. Here's one way to do that: + + -*-byte-compile-dynamic-docstrings: nil;-*- + + -- Variable: byte-compile-dynamic-docstrings + If this is non-`nil', the byte compiler generates compiled files + that are set up for dynamic loading of documentation strings. + Default: t. + + The dynamic documentation string feature writes compiled files that +use a special Lisp reader construct, `#@COUNT'. This construct skips +the next COUNT characters. It also uses the `#$' construct, which +stands for "the name of this file, as a string." It is best not to use +these constructs in Lisp source files. + + +File: lispref.info, Node: Dynamic Loading, Next: Eval During Compile, Prev: Docs and Compilation, Up: Byte Compilation + +21.5 Dynamic Loading of Individual Functions +============================================ + +When you compile a file, you can optionally enable the "dynamic +function loading" feature (also known as "lazy loading"). With dynamic +function loading, loading the file doesn't fully read the function +definitions in the file. Instead, each function definition contains a +place-holder which refers to the file. The first time each function is +called, it reads the full definition from the file, to replace the +place-holder. + + The advantage of dynamic function loading is that loading the file +becomes much faster. This is a good thing for a file which contains +many separate commands, provided that using one of them does not imply +you will soon (or ever) use the rest. A specialized mode which provides +many keyboard commands often has that usage pattern: a user may invoke +the mode, but use only a few of the commands it provides. + + The dynamic loading feature has certain disadvantages: + + * If you delete or move the compiled file after loading it, Emacs + can no longer load the remaining function definitions not already + loaded. + + * If you alter the compiled file (such as by compiling a new + version), then trying to load any function not already loaded will + get nonsense results. + + If you compile a new version of the file, the best thing to do is +immediately load the new compiled file. That will prevent any future +problems. + + The byte compiler uses the dynamic function loading feature if the +variable `byte-compile-dynamic' is non-`nil' at compilation time. Do +not set this variable globally, since dynamic loading is desirable only +for certain files. Instead, enable the feature for specific source +files with file-local variable bindings, like this: + + -*-byte-compile-dynamic: t;-*- + + -- Variable: byte-compile-dynamic + If this is non-`nil', the byte compiler generates compiled files + that are set up for dynamic function loading. Default: nil. + + -- Function: fetch-bytecode function + This immediately finishes loading the definition of FUNCTION from + its byte-compiled file, if it is not fully loaded already. The + argument FUNCTION may be a compiled-function object or a function + name. + + +File: lispref.info, Node: Eval During Compile, Next: Compiled-Function Objects, Prev: Dynamic Loading, Up: Byte Compilation + +21.6 Evaluation During Compilation +================================== + +These features permit you to write code to be evaluated during +compilation of a program. + + -- Special Form: eval-and-compile body + This form marks BODY to be evaluated both when you compile the + containing code and when you run it (whether compiled or not). + + You can get a similar result by putting BODY in a separate file + and referring to that file with `require'. Using `require' is + preferable if there is a substantial amount of code to be executed + in this way. + + -- Special Form: eval-when-compile body + This form marks BODY to be evaluated at compile time and not when + the compiled program is loaded. The result of evaluation by the + compiler becomes a constant which appears in the compiled program. + When the program is interpreted, not compiled at all, BODY is + evaluated normally. + + At top level, this is analogous to the Common Lisp idiom + `(eval-when (compile eval) ...)'. Elsewhere, the Common Lisp `#.' + reader macro (but not when interpreting) is closer to what + `eval-when-compile' does. + + +File: lispref.info, Node: Compiled-Function Objects, Next: Disassembly, Prev: Eval During Compile, Up: Byte Compilation + +21.7 Compiled-Function Objects +============================== + +Byte-compiled functions have a special data type: they are +"compiled-function objects". The evaluator handles this data type +specially when it appears as a function to be called. + + The printed representation for a compiled-function object normally +begins with `#'. However, if the +variable `print-readably' is non-`nil', the object is printed beginning +with `#[' and ending with `]'. This representation can be read +directly by the Lisp reader, and is used in byte-compiled files (those +ending in `.elc'). + + In Emacs version 18, there was no compiled-function object data type; +compiled functions used the function `byte-code' to run the byte code. + + A compiled-function object has a number of different attributes. +They are: + +ARGLIST + The list of argument symbols. + +INSTRUCTIONS + The string containing the byte-code instructions. + +CONSTANTS + The vector of Lisp objects referenced by the byte code. These + include symbols used as function names and variable names. + +STACK-DEPTH + The maximum stack size this function needs. + +DOC-STRING + The documentation string (if any); otherwise, `nil'. The value may + be a number or a list, in case the documentation string is stored + in a file. Use the function `documentation' to get the real + documentation string (*note Accessing Documentation::). + +INTERACTIVE + The interactive spec (if any). This can be a string or a Lisp + expression. It is `nil' for a function that isn't interactive. + +DOMAIN + The domain (if any). This is only meaningful if I18N3 + (message-translation) support was compiled into XEmacs. This is a + string defining which domain to find the translation for the + documentation string and interactive prompt. *Note Domain + Specification::. + + Here's an example of a compiled-function object, in printed +representation. It is the definition of the command `backward-sexp'. + + (symbol-function 'backward-sexp) + => # + + The primitive way to create a compiled-function object is with +`make-byte-code': + + -- Function: make-byte-code arglist instructions constants stack-depth + &optional doc-string interactive + This function constructs and returns a compiled-function object + with the specified attributes. + + _Please note:_ Unlike all other Emacs-lisp functions, calling this + with five arguments is _not_ the same as calling it with six + arguments, the last of which is `nil'. If the INTERACTIVE arg is + specified as `nil', then that means that this function was defined + with `(interactive)'. If the arg is not specified, then that means + the function is not interactive. This is terrible behavior which + is retained for compatibility with old `.elc' files which expected + these semantics. + + You should not try to come up with the elements for a +compiled-function object yourself, because if they are inconsistent, +XEmacs may crash when you call the function. Always leave it to the +byte compiler to create these objects; it makes the elements consistent +(we hope). + + The following primitives are provided for accessing the elements of +a compiled-function object. + + -- Function: compiled-function-arglist function + This function returns the argument list of compiled-function object + FUNCTION. + + -- Function: compiled-function-instructions function + This function returns a string describing the byte-code + instructions of compiled-function object FUNCTION. + + -- Function: compiled-function-constants function + This function returns the vector of Lisp objects referenced by + compiled-function object FUNCTION. + + -- Function: compiled-function-stack-depth function + This function returns the maximum stack size needed by + compiled-function object FUNCTION. + + -- Function: compiled-function-doc-string function + This function returns the doc string of compiled-function object + FUNCTION, if available. + + -- Function: compiled-function-interactive function + This function returns the interactive spec of compiled-function + object FUNCTION, if any. The return value is `nil' or a + two-element list, the first element of which is the symbol + `interactive' and the second element is the interactive spec (a + string or Lisp form). + + -- Function: compiled-function-domain function + This function returns the domain of compiled-function object + FUNCTION, if any. The result will be a string or `nil'. *Note + Domain Specification::. + + +File: lispref.info, Node: Disassembly, Next: Different Behavior, Prev: Compiled-Function Objects, Up: Byte Compilation + +21.8 Disassembled Byte-Code +=========================== + +People do not write byte-code; that job is left to the byte compiler. +But we provide a disassembler to satisfy a cat-like curiosity. The +disassembler converts the byte-compiled code into humanly readable form. + + The byte-code interpreter is implemented as a simple stack machine. +It pushes values onto a stack of its own, then pops them off to use them +in calculations whose results are themselves pushed back on the stack. +When a byte-code function returns, it pops a value off the stack and +returns it as the value of the function. + + In addition to the stack, byte-code functions can use, bind, and set +ordinary Lisp variables, by transferring values between variables and +the stack. + + -- Command: disassemble object &optional stream + This function prints the disassembled code for OBJECT. If STREAM + is supplied, then output goes there. Otherwise, the disassembled + code is printed to the stream `standard-output'. The argument + OBJECT can be a function name or a lambda expression. + + As a special exception, if this function is used interactively, it + outputs to a buffer named `*Disassemble*'. + + Here are two examples of using the `disassemble' function. We have +added explanatory comments to help you relate the byte-code to the Lisp +source; these do not appear in the output of `disassemble'. + + (defun factorial (integer) + "Compute factorial of an integer." + (if (= 1 integer) 1 + (* integer (factorial (1- integer))))) + => factorial + + (factorial 4) + => 24 + + (disassemble 'factorial) + -| byte-code for factorial: + doc: Compute factorial of an integer. + args: (integer) + + 0 varref integer ; Get value of `integer' + ; from the environment + ; and push the value + ; onto the stack. + + 1 constant 1 ; Push 1 onto stack. + + 2 eqlsign ; Pop top two values off stack, + ; compare them, + ; and push result onto stack. + + 3 goto-if-nil 1 ; Pop and test top of stack; + ; if `nil', + ; go to label 1 (which is also byte 7), + ; else continue. + + 5 constant 1 ; Push 1 onto top of stack. + + 6 return ; Return the top element + ; of the stack. + + 7:1 varref integer ; Push value of `integer' onto stack. + + 8 constant factorial ; Push `factorial' onto stack. + + 9 varref integer ; Push value of `integer' onto stack. + + 10 sub1 ; Pop `integer', decrement value, + ; push new value onto stack. + + ; Stack now contains: + ; - decremented value of `integer' + ; - `factorial' + ; - value of `integer' + + 15 call 1 ; Call function `factorial' using + ; the first (i.e., the top) element + ; of the stack as the argument; + ; push returned value onto stack. + + ; Stack now contains: + ; - result of recursive + ; call to `factorial' + ; - value of `integer' + + 12 mult ; Pop top two values off the stack, + ; multiply them, + ; pushing the result onto the stack. + + 13 return ; Return the top element + ; of the stack. + => nil + + The `silly-loop' function is somewhat more complex: + + (defun silly-loop (n) + "Return time before and after N iterations of a loop." + (let ((t1 (current-time-string))) + (while (> (setq n (1- n)) + 0)) + (list t1 (current-time-string)))) + => silly-loop + + (disassemble 'silly-loop) + -| byte-code for silly-loop: + doc: Return time before and after N iterations of a loop. + args: (n) + + 0 constant current-time-string ; Push + ; `current-time-string' + ; onto top of stack. + + 1 call 0 ; Call `current-time-string' + ; with no argument, + ; pushing result onto stack. + + 2 varbind t1 ; Pop stack and bind `t1' + ; to popped value. + + 3:1 varref n ; Get value of `n' from + ; the environment and push + ; the value onto the stack. + + 4 sub1 ; Subtract 1 from top of stack. + + 5 dup ; Duplicate the top of the stack; + ; i.e., copy the top of + ; the stack and push the + ; copy onto the stack. + + 6 varset n ; Pop the top of the stack, + ; and set `n' to the value. + + ; In effect, the sequence `dup varset' + ; copies the top of the stack + ; into the value of `n' + ; without popping it. + + 7 constant 0 ; Push 0 onto stack. + + 8 gtr ; Pop top two values off stack, + ; test if N is greater than 0 + ; and push result onto stack. + + 9 goto-if-not-nil 1 ; Goto label 1 (byte 3) if `n' <= 0 + ; (this exits the while loop). + ; else pop top of stack + ; and continue + + 11 varref t1 ; Push value of `t1' onto stack. + + 12 constant current-time-string ; Push + ; `current-time-string' + ; onto top of stack. + + 13 call 0 ; Call `current-time-string' again. + + 14 unbind 1 ; Unbind `t1' in local environment. + + 15 list2 ; Pop top two elements off stack, + ; create a list of them, + ; and push list onto stack. + + 16 return ; Return the top element of the stack. + + => nil + + +File: lispref.info, Node: Different Behavior, Prev: Disassembly, Up: Byte Compilation + +21.9 Different Behavior +======================= + +The intent is that compiled byte-code and the corresponding code +executed by the Lisp interpreter produce identical results. However, +there are some circumstances where the results will differ. + + * Arithmetic operations may be rearranged for efficiency or + compile-time evaluation. When floating point numbers are + involved, this may produce different values or an overflow. + + * Some arithmetic operations may be optimized away. For example, the + expression `(+ x)' may be optimized to simply `x'. If the value + of `x' is a marker, then the value will be a marker instead of an + integer. If the value of `x' is a cons cell, then the interpreter + will issue an error, while the bytecode will not. + + If you're trying to use `(+ OBJECT 0)' to convert OBJECT to + integer, consider using an explicit conversion function, which is + clearer and guaranteed to work. Instead of `(+ MARKER 0)', use + `(marker-position MARKER)'. Instead of `(+ CHAR 0)', use + `(char-int CHAR)'. + + For maximal equivalence between interpreted and compiled code, the +variables `byte-compile-delete-errors' and `byte-compile-optimize' can +be set to `nil', but this is not recommended. + + +File: lispref.info, Node: Debugging, Next: Read and Print, Prev: Byte Compilation, Up: Top + +22 Debugging Lisp Programs +************************** + +There are three ways to investigate a problem in an XEmacs Lisp program, +depending on what you are doing with the program when the problem +appears. + + * If the problem occurs when you run the program, you can use a Lisp + debugger (either the default debugger or Edebug) to investigate + what is happening during execution. + + * If the problem is syntactic, so that Lisp cannot even read the + program, you can use the XEmacs facilities for editing Lisp to + localize it. + + * If the problem occurs when trying to compile the program with the + byte compiler, you need to know how to examine the compiler's + input buffer. + +* Menu: + +* Debugger:: How the XEmacs Lisp debugger is implemented. +* Syntax Errors:: How to find syntax errors. +* Compilation Errors:: How to find errors that show up in byte compilation. +* Edebug:: A source-level XEmacs Lisp debugger. + + Another useful debugging tool is the dribble file. When a dribble +file is open, XEmacs copies all keyboard input characters to that file. +Afterward, you can examine the file to find out what input was used. +*Note Terminal Input::. + + For debugging problems in terminal descriptions, the +`open-termscript' function can be useful. *Note Terminal Output::. + + +File: lispref.info, Node: Debugger, Next: Syntax Errors, Up: Debugging + +22.1 The Lisp Debugger +====================== + +The "Lisp debugger" provides the ability to suspend evaluation of a +form. While evaluation is suspended (a state that is commonly known as +a "break"), you may examine the run time stack, examine the values of +local or global variables, or change those values. Since a break is a +recursive edit, all the usual editing facilities of XEmacs are +available; you can even run programs that will enter the debugger +recursively. *Note Recursive Editing::. + +* Menu: + +* Error Debugging:: Entering the debugger when an error happens. +* Infinite Loops:: Stopping and debugging a program that doesn't exit. +* Function Debugging:: Entering it when a certain function is called. +* Explicit Debug:: Entering it at a certain point in the program. +* Using Debugger:: What the debugger does; what you see while in it. +* Debugger Commands:: Commands used while in the debugger. +* Invoking the Debugger:: How to call the function `debug'. +* Internals of Debugger:: Subroutines of the debugger, and global variables. + + +File: lispref.info, Node: Error Debugging, Next: Infinite Loops, Up: Debugger + +22.1.1 Entering the Debugger on an Error +---------------------------------------- + +The most important time to enter the debugger is when a Lisp error +happens. This allows you to investigate the immediate causes of the +error. + + However, entry to the debugger is not a normal consequence of an +error. Many commands frequently get Lisp errors when invoked in +inappropriate contexts (such as `C-f' at the end of the buffer) and +during ordinary editing it would be very unpleasant to enter the +debugger each time this happens. If you want errors to enter the +debugger, set the variable `debug-on-error' to non-`nil'. + + -- User Option: debug-on-error + This variable determines whether the debugger is called when an + error is signaled and not handled. If `debug-on-error' is `t', all + errors call the debugger. If it is `nil', none call the debugger. + + The value can also be a list of error conditions that should call + the debugger. For example, if you set it to the list + `(void-variable)', then only errors about a variable that has no + value invoke the debugger. + + When this variable is non-`nil', Emacs does not catch errors that + happen in process filter functions and sentinels. Therefore, these + errors also can invoke the debugger. *Note Processes::. + + -- User Option: debug-on-signal + This variable is similar to `debug-on-error' but breaks whenever + an error is signalled, regardless of whether it would be handled. + + -- User Option: debug-ignored-errors + This variable specifies certain kinds of errors that should not + enter the debugger. Its value is a list of error condition + symbols and/or regular expressions. If the error has any of those + condition symbols, or if the error message matches any of the + regular expressions, then that error does not enter the debugger, + regardless of the value of `debug-on-error'. + + The normal value of this variable lists several errors that happen + often during editing but rarely result from bugs in Lisp programs. + + To debug an error that happens during loading of the `.emacs' file, +use the option `-debug-init', which binds `debug-on-error' to `t' while +`.emacs' is loaded and inhibits use of `condition-case' to catch init +file errors. + + If your `.emacs' file sets `debug-on-error', the effect may not last +past the end of loading `.emacs'. (This is an undesirable byproduct of +the code that implements the `-debug-init' command line option.) The +best way to make `.emacs' set `debug-on-error' permanently is with +`after-init-hook', like this: + + (add-hook 'after-init-hook + '(lambda () (setq debug-on-error t))) + + +File: lispref.info, Node: Infinite Loops, Next: Function Debugging, Prev: Error Debugging, Up: Debugger + +22.1.2 Debugging Infinite Loops +------------------------------- + +When a program loops infinitely and fails to return, your first problem +is to stop the loop. On most operating systems, you can do this with +`C-g', which causes quit. + + Ordinary quitting gives no information about why the program was +looping. To get more information, you can set the variable +`debug-on-quit' to non-`nil'. Quitting with `C-g' is not considered an +error, and `debug-on-error' has no effect on the handling of `C-g'. +Likewise, `debug-on-quit' has no effect on errors. + + Once you have the debugger running in the middle of the infinite +loop, you can proceed from the debugger using the stepping commands. +If you step through the entire loop, you will probably get enough +information to solve the problem. + + -- User Option: debug-on-quit + This variable determines whether the debugger is called when `quit' + is signaled and not handled. If `debug-on-quit' is non-`nil', + then the debugger is called whenever you quit (that is, type + `C-g'). If `debug-on-quit' is `nil', then the debugger is not + called when you quit. *Note Quitting::. + + +File: lispref.info, Node: Function Debugging, Next: Explicit Debug, Prev: Infinite Loops, Up: Debugger + +22.1.3 Entering the Debugger on a Function Call +----------------------------------------------- + +To investigate a problem that happens in the middle of a program, one +useful technique is to enter the debugger whenever a certain function is +called. You can do this to the function in which the problem occurs, +and then step through the function, or you can do this to a function +called shortly before the problem, step quickly over the call to that +function, and then step through its caller. + + -- Command: debug-on-entry function-name + This function requests FUNCTION-NAME to invoke the debugger each + time it is called. It works by inserting the form `(debug + 'debug)' into the function definition as the first form. + + Any function defined as Lisp code may be set to break on entry, + regardless of whether it is interpreted code or compiled code. If + the function is a command, it will enter the debugger when called + from Lisp and when called interactively (after the reading of the + arguments). You can't debug primitive functions (i.e., those + written in C) this way. + + When `debug-on-entry' is called interactively, it prompts for + FUNCTION-NAME in the minibuffer. + + If the function is already set up to invoke the debugger on entry, + `debug-on-entry' does nothing. + + *Please note:* if you redefine a function after using + `debug-on-entry' on it, the code to enter the debugger is lost. + + `debug-on-entry' returns FUNCTION-NAME. + + (defun fact (n) + (if (zerop n) 1 + (* n (fact (1- n))))) + => fact + (debug-on-entry 'fact) + => fact + (fact 3) + + ------ Buffer: *Backtrace* ------ + Entering: + * fact(3) + eval-region(4870 4878 t) + byte-code("...") + eval-last-sexp(nil) + (let ...) + eval-insert-last-sexp(nil) + * call-interactively(eval-insert-last-sexp) + ------ Buffer: *Backtrace* ------ + + (symbol-function 'fact) + => (lambda (n) + (debug (quote debug)) + (if (zerop n) 1 (* n (fact (1- n))))) + + -- Command: cancel-debug-on-entry &optional function-name + This function undoes the effect of `debug-on-entry' on + FUNCTION-NAME. When called interactively, it prompts for + FUNCTION-NAME in the minibuffer. If FUNCTION-NAME is `nil' or the + empty string, it cancels debugging for all functions. + + If `cancel-debug-on-entry' is called more than once on the same + function, the second call does nothing. `cancel-debug-on-entry' + returns FUNCTION-NAME. + + +File: lispref.info, Node: Explicit Debug, Next: Using Debugger, Prev: Function Debugging, Up: Debugger + +22.1.4 Explicit Entry to the Debugger +------------------------------------- + +You can cause the debugger to be called at a certain point in your +program by writing the expression `(debug)' at that point. To do this, +visit the source file, insert the text `(debug)' at the proper place, +and type `C-M-x'. Be sure to undo this insertion before you save the +file! + + The place where you insert `(debug)' must be a place where an +additional form can be evaluated and its value ignored. (If the value +of `(debug)' isn't ignored, it will alter the execution of the +program!) The most common suitable places are inside a `progn' or an +implicit `progn' (*note Sequencing::). + + +File: lispref.info, Node: Using Debugger, Next: Debugger Commands, Prev: Explicit Debug, Up: Debugger + +22.1.5 Using the Debugger +------------------------- + +When the debugger is entered, it displays the previously selected +buffer in one window and a buffer named `*Backtrace*' in another +window. The backtrace buffer contains one line for each level of Lisp +function execution currently going on. At the beginning of this buffer +is a message describing the reason that the debugger was invoked (such +as the error message and associated data, if it was invoked due to an +error). + + The backtrace buffer is read-only and uses a special major mode, +Debugger mode, in which letters are defined as debugger commands. The +usual XEmacs editing commands are available; thus, you can switch +windows to examine the buffer that was being edited at the time of the +error, switch buffers, visit files, or do any other sort of editing. +However, the debugger is a recursive editing level (*note Recursive +Editing::) and it is wise to go back to the backtrace buffer and exit +the debugger (with the `q' command) when you are finished with it. +Exiting the debugger gets out of the recursive edit and kills the +backtrace buffer. + + The backtrace buffer shows you the functions that are executing and +their argument values. It also allows you to specify a stack frame by +moving point to the line describing that frame. (A stack frame is the +place where the Lisp interpreter records information about a particular +invocation of a function.) The frame whose line point is on is +considered the "current frame". Some of the debugger commands operate +on the current frame. + + The debugger itself must be run byte-compiled, since it makes +assumptions about how many stack frames are used for the debugger +itself. These assumptions are false if the debugger is running +interpreted. + + +File: lispref.info, Node: Debugger Commands, Next: Invoking the Debugger, Prev: Using Debugger, Up: Debugger + +22.1.6 Debugger Commands +------------------------ + +Inside the debugger (in Debugger mode), these special commands are +available in addition to the usual cursor motion commands. (Keep in +mind that all the usual facilities of XEmacs, such as switching windows +or buffers, are still available.) + + The most important use of debugger commands is for stepping through +code, so that you can see how control flows. The debugger can step +through the control structures of an interpreted function, but cannot do +so in a byte-compiled function. If you would like to step through a +byte-compiled function, replace it with an interpreted definition of the +same function. (To do this, visit the source file for the function and +type `C-M-x' on its definition.) + + Here is a list of Debugger mode commands: + +`c' + Exit the debugger and continue execution. This resumes execution + of the program as if the debugger had never been entered (aside + from the effect of any variables or data structures you may have + changed while inside the debugger). + + Continuing when an error or quit was signalled will cause the + normal action of the signalling to take place. If you do not want + this to happen, but instead want the program execution to continue + as if the call to `signal' did not occur, use the `r' command. + +`d' + Continue execution, but enter the debugger the next time any Lisp + function is called. This allows you to step through the + subexpressions of an expression, seeing what values the + subexpressions compute, and what else they do. + + The stack frame made for the function call which enters the + debugger in this way will be flagged automatically so that the + debugger will be called again when the frame is exited. You can + use the `u' command to cancel this flag. + +`b' + Flag the current frame so that the debugger will be entered when + the frame is exited. Frames flagged in this way are marked with + stars in the backtrace buffer. + +`u' + Don't enter the debugger when the current frame is exited. This + cancels a `b' command on that frame. + +`e' + Read a Lisp expression in the minibuffer, evaluate it, and print + the value in the echo area. The debugger alters certain important + variables, and the current buffer, as part of its operation; `e' + temporarily restores their outside-the-debugger values so you can + examine them. This makes the debugger more transparent. By + contrast, `M-:' does nothing special in the debugger; it shows you + the variable values within the debugger. + +`q' + Terminate the program being debugged; return to top-level XEmacs + command execution. + + If the debugger was entered due to a `C-g' but you really want to + quit, and not debug, use the `q' command. + +`r' + Return a value from the debugger. The value is computed by + reading an expression with the minibuffer and evaluating it. + + The `r' command is useful when the debugger was invoked due to exit + from a Lisp call frame (as requested with `b'); then the value + specified in the `r' command is used as the value of that frame. + It is also useful if you call `debug' and use its return value. + + If the debugger was entered at the beginning of a function call, + `r' has the same effect as `c', and the specified return value + does not matter. + + If the debugger was entered through a call to `signal' (i.e. as a + result of an error or quit), then returning a value will cause the + call to `signal' itself to return, rather than throwing to + top-level or invoking a handler, as is normal. This allows you to + correct an error (e.g. the type of an argument was wrong) or + continue from a `debug-on-quit' as if it never happened. + + Note that some errors (e.g. any error signalled using the `error' + function, and many errors signalled from a primitive function) are + not continuable. If you return a value from them and continue + execution, then the error will immediately be signalled again. + Other errors (e.g. wrong-type-argument errors) will be continually + resignalled until the problem is corrected. + + +File: lispref.info, Node: Invoking the Debugger, Next: Internals of Debugger, Prev: Debugger Commands, Up: Debugger + +22.1.7 Invoking the Debugger +---------------------------- + +Here we describe fully the function used to invoke the debugger. + + -- Function: debug &rest debugger-args + This function enters the debugger. It switches buffers to a buffer + named `*Backtrace*' (or `*Backtrace*<2>' if it is the second + recursive entry to the debugger, etc.), and fills it with + information about the stack of Lisp function calls. It then + enters a recursive edit, showing the backtrace buffer in Debugger + mode. + + The Debugger mode `c' and `r' commands exit the recursive edit; + then `debug' switches back to the previous buffer and returns to + whatever called `debug'. This is the only way the function + `debug' can return to its caller. + + If the first of the DEBUGGER-ARGS passed to `debug' is `nil' (or + if it is not one of the special values in the table below), then + `debug' displays the rest of its arguments at the top of the + `*Backtrace*' buffer. This mechanism is used to display a message + to the user. + + However, if the first argument passed to `debug' is one of the + following special values, then it has special significance. + Normally, these values are passed to `debug' only by the internals + of XEmacs and the debugger, and not by programmers calling `debug'. + + The special values are: + + `lambda' + A first argument of `lambda' means `debug' was called because + of entry to a function when `debug-on-next-call' was + non-`nil'. The debugger displays `Entering:' as a line of + text at the top of the buffer. + + `debug' + `debug' as first argument indicates a call to `debug' because + of entry to a function that was set to debug on entry. The + debugger displays `Entering:', just as in the `lambda' case. + It also marks the stack frame for that function so that it + will invoke the debugger when exited. + + `t' + When the first argument is `t', this indicates a call to + `debug' due to evaluation of a list form when + `debug-on-next-call' is non-`nil'. The debugger displays the + following as the top line in the buffer: + + Beginning evaluation of function call form: + + `exit' + When the first argument is `exit', it indicates the exit of a + stack frame previously marked to invoke the debugger on exit. + The second argument given to `debug' in this case is the + value being returned from the frame. The debugger displays + `Return value:' on the top line of the buffer, followed by + the value being returned. + + `error' + When the first argument is `error', the debugger indicates + that it is being entered because an error or `quit' was + signaled and not handled, by displaying `Signaling:' followed + by the error signaled and any arguments to `signal'. For + example, + + (let ((debug-on-error t)) + (/ 1 0)) + + ------ Buffer: *Backtrace* ------ + Signaling: (arith-error) + /(1 0) + ... + ------ Buffer: *Backtrace* ------ + + If an error was signaled, presumably the variable + `debug-on-error' is non-`nil'. If `quit' was signaled, then + presumably the variable `debug-on-quit' is non-`nil'. + + `nil' + Use `nil' as the first of the DEBUGGER-ARGS when you want to + enter the debugger explicitly. The rest of the DEBUGGER-ARGS + are printed on the top line of the buffer. You can use this + feature to display messages--for example, to remind yourself + of the conditions under which `debug' is called. + + +File: lispref.info, Node: Internals of Debugger, Prev: Invoking the Debugger, Up: Debugger + +22.1.8 Internals of the Debugger +-------------------------------- + +This section describes functions and variables used internally by the +debugger. + + -- Variable: debugger + The value of this variable is the function to call to invoke the + debugger. Its value must be a function of any number of arguments + (or, more typically, the name of a function). Presumably this + function will enter some kind of debugger. The default value of + the variable is `debug'. + + The first argument that Lisp hands to the function indicates why it + was called. The convention for arguments is detailed in the + description of `debug'. + + -- Command: backtrace &optional stream detailed + This function prints a trace of Lisp function calls currently + active. This is the function used by `debug' to fill up the + `*Backtrace*' buffer. It is written in C, since it must have + access to the stack to determine which function calls are active. + The return value is always `nil'. + + The backtrace is normally printed to `standard-output', but this + can be changed by specifying a value for STREAM. If DETAILED is + non-`nil', the backtrace also shows places where currently active + variable bindings, catches, condition-cases, and unwind-protects + were made as well as function calls. + + In the following example, a Lisp expression calls `backtrace' + explicitly. This prints the backtrace to the stream + `standard-output': in this case, to the buffer `backtrace-output'. + Each line of the backtrace represents one function call. The + line shows the values of the function's arguments if they are all + known. If they are still being computed, the line says so. The + arguments of special forms are elided. + + (with-output-to-temp-buffer "backtrace-output" + (let ((var 1)) + (save-excursion + (setq var (eval '(progn + (1+ var) + (list 'testing (backtrace)))))))) + + => nil + + ----------- Buffer: backtrace-output ------------ + backtrace() + (list ...computing arguments...) + (progn ...) + eval((progn (1+ var) (list (quote testing) (backtrace)))) + (setq ...) + (save-excursion ...) + (let ...) + (with-output-to-temp-buffer ...) + eval-region(1973 2142 #) + byte-code("... for eval-print-last-sexp ...") + eval-print-last-sexp(nil) + * call-interactively(eval-print-last-sexp) + ----------- Buffer: backtrace-output ------------ + + The character `*' indicates a frame whose debug-on-exit flag is + set. + + -- Variable: debug-on-next-call + If this variable is non-`nil', it says to call the debugger before + the next `eval', `apply' or `funcall'. Entering the debugger sets + `debug-on-next-call' to `nil'. + + The `d' command in the debugger works by setting this variable. + + -- Function: backtrace-debug level flag + This function sets the debug-on-exit flag of the stack frame LEVEL + levels down the stack, giving it the value FLAG. If FLAG is + non-`nil', this will cause the debugger to be entered when that + frame later exits. Even a nonlocal exit through that frame will + enter the debugger. + + This function is used only by the debugger. + + -- Variable: command-debug-status + This variable records the debugging status of the current + interactive command. Each time a command is called interactively, + this variable is bound to `nil'. The debugger can set this + variable to leave information for future debugger invocations + during the same command. + + The advantage, for the debugger, of using this variable rather than + another global variable is that the data will never carry over to a + subsequent command invocation. + + -- Function: backtrace-frame frame-number + The function `backtrace-frame' is intended for use in Lisp + debuggers. It returns information about what computation is + happening in the stack frame FRAME-NUMBER levels down. + + If that frame has not evaluated the arguments yet (or is a special + form), the value is `(nil FUNCTION ARG-FORMS...)'. + + If that frame has evaluated its arguments and called its function + already, the value is `(t FUNCTION ARG-VALUES...)'. + + In the return value, FUNCTION is whatever was supplied as the CAR + of the evaluated list, or a `lambda' expression in the case of a + macro call. If the function has a `&rest' argument, that is + represented as the tail of the list ARG-VALUES. + + If FRAME-NUMBER is out of range, `backtrace-frame' returns `nil'. + + +File: lispref.info, Node: Syntax Errors, Next: Compilation Errors, Prev: Debugger, Up: Debugging + +22.2 Debugging Invalid Lisp Syntax +================================== + +The Lisp reader reports invalid syntax, but cannot say where the real +problem is. For example, the error "End of file during parsing" in +evaluating an expression indicates an excess of open parentheses (or +square brackets). The reader detects this imbalance at the end of the +file, but it cannot figure out where the close parenthesis should have +been. Likewise, "Invalid read syntax: ")"" indicates an excess close +parenthesis or missing open parenthesis, but does not say where the +missing parenthesis belongs. How, then, to find what to change? + + If the problem is not simply an imbalance of parentheses, a useful +technique is to try `C-M-e' at the beginning of each defun, and see if +it goes to the place where that defun appears to end. If it does not, +there is a problem in that defun. + + However, unmatched parentheses are the most common syntax errors in +Lisp, and we can give further advice for those cases. + +* Menu: + +* Excess Open:: How to find a spurious open paren or missing close. +* Excess Close:: How to find a spurious close paren or missing open. + + +File: lispref.info, Node: Excess Open, Next: Excess Close, Up: Syntax Errors + +22.2.1 Excess Open Parentheses +------------------------------ + +The first step is to find the defun that is unbalanced. If there is an +excess open parenthesis, the way to do this is to insert a close +parenthesis at the end of the file and type `C-M-b' (`backward-sexp'). +This will move you to the beginning of the defun that is unbalanced. +(Then type `C- C-_ C-u C-' to set the mark there, undo the +insertion of the close parenthesis, and finally return to the mark.) + + The next step is to determine precisely what is wrong. There is no +way to be sure of this except to study the program, but often the +existing indentation is a clue to where the parentheses should have +been. The easiest way to use this clue is to reindent with `C-M-q' and +see what moves. + + Before you do this, make sure the defun has enough close parentheses. +Otherwise, `C-M-q' will get an error, or will reindent all the rest of +the file until the end. So move to the end of the defun and insert a +close parenthesis there. Don't use `C-M-e' to move there, since that +too will fail to work until the defun is balanced. + + Now you can go to the beginning of the defun and type `C-M-q'. +Usually all the lines from a certain point to the end of the function +will shift to the right. There is probably a missing close parenthesis, +or a superfluous open parenthesis, near that point. (However, don't +assume this is true; study the code to make sure.) Once you have found +the discrepancy, undo the `C-M-q' with `C-_', since the old indentation +is probably appropriate to the intended parentheses. + + After you think you have fixed the problem, use `C-M-q' again. If +the old indentation actually fit the intended nesting of parentheses, +and you have put back those parentheses, `C-M-q' should not change +anything. + + +File: lispref.info, Node: Excess Close, Prev: Excess Open, Up: Syntax Errors + +22.2.2 Excess Close Parentheses +------------------------------- + +To deal with an excess close parenthesis, first insert an open +parenthesis at the beginning of the file, back up over it, and type +`C-M-f' to find the end of the unbalanced defun. (Then type `C- +C-_ C-u C-' to set the mark there, undo the insertion of the open +parenthesis, and finally return to the mark.) + + Then find the actual matching close parenthesis by typing `C-M-f' at +the beginning of the defun. This will leave you somewhere short of the +place where the defun ought to end. It is possible that you will find +a spurious close parenthesis in that vicinity. + + If you don't see a problem at that point, the next thing to do is to +type `C-M-q' at the beginning of the defun. A range of lines will +probably shift left; if so, the missing open parenthesis or spurious +close parenthesis is probably near the first of those lines. (However, +don't assume this is true; study the code to make sure.) Once you have +found the discrepancy, undo the `C-M-q' with `C-_', since the old +indentation is probably appropriate to the intended parentheses. + + After you think you have fixed the problem, use `C-M-q' again. If +the old indentation actually fit the intended nesting of parentheses, +and you have put back those parentheses, `C-M-q' should not change +anything. + + +File: lispref.info, Node: Compilation Errors, Next: Edebug, Prev: Syntax Errors, Up: Debugging + +22.3 Debugging Problems in Compilation +====================================== + +When an error happens during byte compilation, it is normally due to +invalid syntax in the program you are compiling. The compiler prints a +suitable error message in the `*Compile-Log*' buffer, and then stops. +The message may state a function name in which the error was found, or +it may not. Either way, here is how to find out where in the file the +error occurred. + + What you should do is switch to the buffer ` *Compiler Input*'. +(Note that the buffer name starts with a space, so it does not show up +in `M-x list-buffers'.) This buffer contains the program being +compiled, and point shows how far the byte compiler was able to read. + + If the error was due to invalid Lisp syntax, point shows exactly +where the invalid syntax was _detected_. The cause of the error is not +necessarily near by! Use the techniques in the previous section to find +the error. + + If the error was detected while compiling a form that had been read +successfully, then point is located at the end of the form. In this +case, this technique can't localize the error precisely, but can still +show you which function to check. + + +File: lispref.info, Node: Edebug, Prev: Compilation Errors, Up: Top + +22.4 Edebug +=========== + +Edebug is a source-level debugger for XEmacs Lisp programs that +provides the following features: + + * Step through evaluation, stopping before and after each expression. + + * Set conditional or unconditional breakpoints, install embedded + breakpoints, or a global break event. + + * Trace slow or fast stopping briefly at each stop point, or each + breakpoint. + + * Display expression results and evaluate expressions as if outside + of Edebug. Interface with the custom printing package for + printing circular structures. + + * Automatically reevaluate a list of expressions and display their + results each time Edebug updates the display. + + * Output trace info on function enter and exit. + + * Errors stop before the source causing the error. + + * Display backtrace without Edebug calls. + + * Allow specification of argument evaluation for macros and defining + forms. + + * Provide rudimentary coverage testing and display of frequency + counts. + + + The first three sections should tell you enough about Edebug to +enable you to use it. + +* Menu: + +* Using Edebug:: Introduction to use of Edebug. +* Instrumenting:: You must first instrument code. +* Edebug Execution Modes:: Execution modes, stopping more or less often. +* Jumping:: Commands to jump to a specified place. +* Edebug Misc:: Miscellaneous commands. +* Breakpoints:: Setting breakpoints to make the program stop. +* Trapping Errors:: trapping errors with Edebug. +* Edebug Views:: Views inside and outside of Edebug. +* Edebug Eval:: Evaluating expressions within Edebug. +* Eval List:: Automatic expression evaluation. +* Reading in Edebug:: Customization of reading. +* Printing in Edebug:: Customization of printing. +* Tracing:: How to produce tracing output. +* Coverage Testing:: How to test evaluation coverage. +* The Outside Context:: Data that Edebug saves and restores. +* Instrumenting Macro Calls:: Specifying how to handle macro calls. +* Edebug Options:: Option variables for customizing Edebug. + + +File: lispref.info, Node: Using Edebug, Next: Instrumenting, Up: Edebug + +22.4.1 Using Edebug +------------------- + +To debug an XEmacs Lisp program with Edebug, you must first +"instrument" the Lisp code that you want to debug. If you want to just +try it now, load `edebug.el', move point into a definition and do `C-u +C-M-x' (`eval-defun' with a prefix argument). See *Note +Instrumenting:: for alternative ways to instrument code. + + Once a function is instrumented, any call to the function activates +Edebug. Activating Edebug may stop execution and let you step through +the function, or it may update the display and continue execution while +checking for debugging commands, depending on the selected Edebug +execution mode. The initial execution mode is `step', by default, +which does stop execution. *Note Edebug Execution Modes::. + + Within Edebug, you normally view an XEmacs buffer showing the source +of the Lisp function you are debugging. This is referred to as the +"source code buffer"--but note that it is not always the same buffer +depending on which function is currently being executed. + + An arrow at the left margin indicates the line where the function is +executing. Point initially shows where within the line the function is +executing, but you can move point yourself. + + If you instrument the definition of `fac' (shown below) and then +execute `(fac 3)', here is what you normally see. Point is at the +open-parenthesis before `if'. + + (defun fac (n) + =>-!-(if (< 0 n) + (* n (fac (1- n))) + 1)) + + The places within a function where Edebug can stop execution are +called "stop points". These occur both before and after each +subexpression that is a list, and also after each variable reference. +Here we show with periods the stop points found in the function `fac': + + (defun fac (n) + .(if .(< 0 n.). + .(* n. .(fac (1- n.).).). + 1).) + + While the source code buffer is selected, the special commands of +Edebug are available in it, in addition to the commands of XEmacs Lisp +mode. (The buffer is temporarily made read-only, however.) For +example, you can type the Edebug command to execute until the +next stop point. If you type once after entry to `fac', here is +the display you will see: + + (defun fac (n) + =>(if -!-(< 0 n) + (* n (fac (1- n))) + 1)) + + When Edebug stops execution after an expression, it displays the +expression's value in the echo area. + + Other frequently used commands are `b' to set a breakpoint at a stop +point, `g' to execute until a breakpoint is reached, and `q' to exit to +the top-level command loop. Type `?' to display a list of all Edebug +commands. + + +File: lispref.info, Node: Instrumenting, Next: Edebug Execution Modes, Prev: Using Edebug, Up: Edebug + +22.4.2 Instrumenting for Edebug +------------------------------- + +In order to use Edebug to debug Lisp code, you must first "instrument" +the code. Instrumenting a form inserts additional code into it which +invokes Edebug at the proper places. Furthermore, if Edebug detects a +syntax error while instrumenting, point is left at the erroneous code +and an `invalid-read-syntax' error is signaled. + + Once you have loaded Edebug, the command `C-M-x' (`eval-defun') is +redefined so that when invoked with a prefix argument on a definition, +it instruments the definition before evaluating it. (The source code +itself is not modified.) If the variable `edebug-all-defs' is +non-`nil', that inverts the meaning of the prefix argument: then +`C-M-x' instruments the definition _unless_ it has a prefix argument. +The default value of `edebug-all-defs' is `nil'. The command `M-x +edebug-all-defs' toggles the value of the variable `edebug-all-defs'. + + If `edebug-all-defs' is non-`nil', then the commands `eval-region', +`eval-current-buffer', and `eval-buffer' also instrument any +definitions they evaluate. Similarly, `edebug-all-forms' controls +whether `eval-region' should instrument _any_ form, even non-defining +forms. This doesn't apply to loading or evaluations in the minibuffer. +The command `M-x edebug-all-forms' toggles this option. + + Another command, `M-x edebug-eval-top-level-form', is available to +instrument any top-level form regardless of the value of +`edebug-all-defs' or `edebug-all-forms'. + + Just before Edebug instruments any code, it calls any functions in +the variable `edebug-setup-hook' and resets its value to `nil'. You +could use this to load up Edebug specifications associated with a +package you are using but only when you also use Edebug. For example, +`my-specs.el' may be loaded automatically when you use `my-package' +with Edebug by including the following code in `my-package.el'. + + (add-hook 'edebug-setup-hook + (function (lambda () (require 'my-specs)))) + + While Edebug is active, the command `I' (`edebug-instrument-callee') +instruments the definition of the function or macro called by the list +form after point, if is not already instrumented. If the location of +the definition is not known to Edebug, this command cannot be used. +After loading Edebug, `eval-region' records the position of every +definition it evaluates, even if not instrumenting it. Also see the +command `i' (*Note Jumping::) which steps into the callee. + + Edebug knows how to instrument all the standard special forms, an +interactive form with an expression argument, anonymous lambda +expressions, and other defining forms. (Specifications for macros +defined by `cl.el' (version 2.03) are provided in `cl-specs.el'.) +Edebug cannot know what a user-defined macro will do with the arguments +of a macro call so you must tell it. See *Note Instrumenting Macro +Calls:: for the details. + + Note that a couple ways remain to evaluate expressions without +instrumenting them. Loading a file via the `load' subroutine does not +instrument expressions for Edebug. Evaluations in the minibuffer via +`eval-expression' (`M-ESC') are not instrumented. + + To remove instrumentation from a definition, simply reevaluate it +with one of the non-instrumenting commands, or reload the file. + + See *Note Edebug Eval:: for other evaluation functions available +inside of Edebug. + + +File: lispref.info, Node: Edebug Execution Modes, Next: Jumping, Prev: Instrumenting, Up: Edebug + +22.4.3 Edebug Execution Modes +----------------------------- + +Edebug supports several execution modes for running the program you are +debugging. We call these alternatives "Edebug execution modes"; do not +confuse them with major or minor modes. The current Edebug execution +mode determines how Edebug displays the progress of the evaluation, +whether it stops at each stop point, or continues to the next +breakpoint, for example. + + Normally, you specify the Edebug execution mode by typing a command +to continue the program in a certain mode. Here is a table of these +commands. All except for `S' resume execution of the program, at least +for a certain distance. + +`S' + Stop: don't execute any more of the program for now, just wait for + more Edebug commands (`edebug-stop'). + +`' + Step: stop at the next stop point encountered (`edebug-step-mode'). + +`n' + Next: stop at the next stop point encountered after an expression + (`edebug-next-mode'). Also see `edebug-forward-sexp' in *Note + Edebug Misc::. + +`t' + Trace: pause one second at each Edebug stop point + (`edebug-trace-mode'). + +`T' + Rapid trace: update at each stop point, but don't actually pause + (`edebug-Trace-fast-mode'). + +`g' + Go: run until the next breakpoint (`edebug-go-mode'). *Note + Breakpoints::. + +`c' + Continue: pause for one second at each breakpoint, but don't stop + (`edebug-continue-mode'). + +`C' + Rapid continue: update at each breakpoint, but don't actually pause + (`edebug-Continue-fast-mode'). + +`G' + Go non-stop: ignore breakpoints (`edebug-Go-nonstop-mode'). You + can still stop the program by hitting any key. + + In general, the execution modes earlier in the above list run the +program more slowly or stop sooner. + + When you enter a new Edebug level, the initial execution mode comes +from the value of the variable `edebug-initial-mode'. By default, this +specifies `step' mode. Note that you may reenter the same Edebug level +several times if, for example, an instrumented function is called +several times from one command. + + While executing or tracing, you can interrupt the execution by typing +any Edebug command. Edebug stops the program at the next stop point and +then executes the command that you typed. For example, typing `t' +during execution switches to trace mode at the next stop point. You can +use `S' to stop execution without doing anything else. + + If your function happens to read input, a character you hit +intending to interrupt execution may be read by the function instead. +You can avoid such unintended results by paying attention to when your +program wants input. + + Keyboard macros containing Edebug commands do not work; when you exit +from Edebug, to resume the program, whether you are defining or +executing a keyboard macro is forgotten. Also, defining or executing a +keyboard macro outside of Edebug does not affect the command loop inside +Edebug. This is usually an advantage. But see +`edebug-continue-kbd-macro'. + + +File: lispref.info, Node: Jumping, Next: Edebug Misc, Prev: Edebug Execution Modes, Up: Edebug + +22.4.4 Jumping +-------------- + +Commands described here let you jump to a specified location. All, +except `i', use temporary breakpoints to establish the stop point and +then switch to `go' mode. Any other breakpoint reached before the +intended stop point will also stop execution. See *Note Breakpoints:: +for the details on breakpoints. + +`f' + Run the program forward over one expression + (`edebug-forward-sexp'). More precisely, set a temporary + breakpoint at the position that `C-M-f' would reach, then execute + in `go' mode so that the program will stop at breakpoints. + + With a prefix argument N, the temporary breakpoint is placed N + sexps beyond point. If the containing list ends before N more + elements, then the place to stop is after the containing + expression. + + Be careful that the position `C-M-f' finds is a place that the + program will really get to; this may not be true in a `cond', for + example. + + This command does `forward-sexp' starting at point rather than the + stop point. If you want to execute one expression from the + current stop point, type `w' first, to move point there. + +`o' + Continue "out of" an expression (`edebug-step-out'). It places a + temporary breakpoint at the end of the sexp containing point. + + If the containing sexp is a function definition itself, it + continues until just before the last sexp in the definition. If + that is where you are now, it returns from the function and then + stops. In other words, this command does not exit the currently + executing function unless you are positioned after the last sexp. + +`I' + Step into the function or macro after point after first ensuring + that it is instrumented. It does this by calling + `edebug-on-entry' and then switching to `go' mode. + + Although the automatic instrumentation is convenient, it is not + later automatically uninstrumented. + +`h' + Proceed to the stop point near where point is using a temporary + breakpoint (`edebug-goto-here'). + + + All the commands in this section may fail to work as expected in case +of nonlocal exit, because a nonlocal exit can bypass the temporary +breakpoint where you expected the program to stop. + + +File: lispref.info, Node: Edebug Misc, Next: Breakpoints, Prev: Jumping, Up: Edebug + +22.4.5 Miscellaneous +-------------------- + +Some miscellaneous commands are described here. + +`?' + Display the help message for Edebug (`edebug-help'). + +`C-]' + Abort one level back to the previous command level + (`abort-recursive-edit'). + +`q' + Return to the top level editor command loop (`top-level'). This + exits all recursive editing levels, including all levels of Edebug + activity. However, instrumented code protected with + `unwind-protect' or `condition-case' forms may resume debugging. + +`Q' + Like `q' but don't stop even for protected code + (`top-level-nonstop'). + +`r' + Redisplay the most recently known expression result in the echo + area (`edebug-previous-result'). + +`d' + Display a backtrace, excluding Edebug's own functions for clarity + (`edebug-backtrace'). + + You cannot use debugger commands in the backtrace buffer in Edebug + as you would in the standard debugger. + + The backtrace buffer is killed automatically when you continue + execution. + + From the Edebug recursive edit, you may invoke commands that activate +Edebug again recursively. Any time Edebug is active, you can quit to +the top level with `q' or abort one recursive edit level with `C-]'. +You can display a backtrace of all the pending evaluations with `d'. + + +File: lispref.info, Node: Breakpoints, Next: Trapping Errors, Prev: Edebug Misc, Up: Edebug + +22.4.6 Breakpoints +------------------ + +There are three more ways to stop execution once it has started: +breakpoints, the global break condition, and embedded breakpoints. + + While using Edebug, you can specify "breakpoints" in the program you +are testing: points where execution should stop. You can set a +breakpoint at any stop point, as defined in *Note Using Edebug::. For +setting and unsetting breakpoints, the stop point that is affected is +the first one at or after point in the source code buffer. Here are the +Edebug commands for breakpoints: + +`b' + Set a breakpoint at the stop point at or after point + (`edebug-set-breakpoint'). If you use a prefix argument, the + breakpoint is temporary (it turns off the first time it stops the + program). + +`u' + Unset the breakpoint (if any) at the stop point at or after the + current point (`edebug-unset-breakpoint'). + +`x CONDITION ' + Set a conditional breakpoint which stops the program only if + CONDITION evaluates to a non-`nil' value + (`edebug-set-conditional-breakpoint'). If you use a prefix + argument, the breakpoint is temporary (it turns off the first time + it stops the program). + +`B' + Move point to the next breakpoint in the definition + (`edebug-next-breakpoint'). + + While in Edebug, you can set a breakpoint with `b' and unset one +with `u'. First you must move point to a position at or before the +desired Edebug stop point, then hit the key to change the breakpoint. +Unsetting a breakpoint that has not been set does nothing. + + Reevaluating or reinstrumenting a definition clears all its +breakpoints. + + A "conditional breakpoint" tests a condition each time the program +gets there. To set a conditional breakpoint, use `x', and specify the +condition expression in the minibuffer. Setting a conditional +breakpoint at a stop point that already has a conditional breakpoint +puts the current condition expression in the minibuffer so you can edit +it. + + You can make both conditional and unconditional breakpoints +"temporary" by using a prefix arg to the command to set the breakpoint. +After breaking at a temporary breakpoint, it is automatically cleared. + + Edebug always stops or pauses at a breakpoint except when the Edebug +mode is `Go-nonstop'. In that mode, it ignores breakpoints entirely. + + To find out where your breakpoints are, use `B', which moves point +to the next breakpoint in the definition following point, or to the +first breakpoint if there are no following breakpoints. This command +does not continue execution--it just moves point in the buffer. + +* Menu: + +* Global Break Condition:: Breaking on an event. +* Embedded Breakpoints:: Embedding breakpoints in code. + + +File: lispref.info, Node: Global Break Condition, Next: Embedded Breakpoints, Up: Breakpoints + +22.4.6.1 Global Break Condition +............................... + +In contrast to breaking when execution reaches specified locations, you +can also cause a break when a certain event occurs. The "global break +condition" is a condition that is repeatedly evaluated at every stop +point. If it evaluates to a non-`nil' value, then execution is stopped +or paused depending on the execution mode, just like a breakpoint. Any +errors that might occur as a result of evaluating the condition are +ignored, as if the result were `nil'. + + You can set or edit the condition expression, stored in +`edebug-global-break-condition', using `X' +(`edebug-set-global-break-condition'). + + Using the global break condition is perhaps the fastest way to find +where in your code some event occurs, but since it is rather expensive +you should reset the condition to `nil' when not in use. + + +File: lispref.info, Node: Embedded Breakpoints, Prev: Global Break Condition, Up: Breakpoints + +22.4.6.2 Embedded Breakpoints +............................. + +Since all breakpoints in a definition are cleared each time you +reinstrument it, you might rather create an "embedded breakpoint" which +is simply a call to the function `edebug'. You can, of course, make +such a call conditional. For example, in the `fac' function, insert +the first line as shown below to stop when the argument reaches zero: + + (defun fac (n) + (if (= n 0) (edebug)) + (if (< 0 n) + (* n (fac (1- n))) + 1)) + + When the `fac' definition is instrumented and the function is +called, Edebug will stop before the call to `edebug'. Depending on the +execution mode, Edebug will stop or pause. + + However, if no instrumented code is being executed, calling `edebug' +will instead invoke `debug'. Calling `debug' will always invoke the +standard backtrace debugger. + + +File: lispref.info, Node: Trapping Errors, Next: Edebug Views, Prev: Breakpoints, Up: Edebug + +22.4.7 Trapping Errors +---------------------- + +An error may be signaled by subroutines or XEmacs Lisp code. If a +signal is not handled by a `condition-case', this indicates an +unrecognized situation has occurred. If Edebug is not active when an +unhandled error is signaled, `debug' is run normally (if +`debug-on-error' is non-`nil'). But while Edebug is active, +`debug-on-error' and `debug-on-quit' are bound to `edebug-on-error' and +`edebug-on-quit', which are both `t' by default. Actually, if +`debug-on-error' already has a non-`nil' value, that value is still +used. + + It is best to change the values of `edebug-on-error' or +`edebug-on-quit' when Edebug is not active since their values won't be +used until the next time Edebug is invoked at a deeper command level. +If you only change `debug-on-error' or `debug-on-quit' while Edebug is +active, these changes will be forgotten when Edebug becomes inactive. +Furthermore, during Edebug's recursive edit, these variables are bound +to the values they had outside of Edebug. + + Edebug shows you the last stop point that it knew about before the +error was signaled. This may be the location of a call to a function +which was not instrumented, within which the error actually occurred. +For an unbound variable error, the last known stop point might be quite +distant from the offending variable. If the cause of the error is not +obvious at first, note that you can also get a full backtrace inside of +Edebug (see *Note Edebug Misc::). + + Edebug can also trap signals even if they are handled. If +`debug-on-error' is a list of signal names, Edebug will stop when any +of these errors are signaled. Edebug shows you the last known stop +point just as for unhandled errors. After you continue execution, the +error is signaled again (but without being caught by Edebug). Edebug +can only trap errors that are handled if they are signaled in Lisp code +(not subroutines) since it does so by temporarily replacing the +`signal' function. + + +File: lispref.info, Node: Edebug Views, Next: Edebug Eval, Prev: Trapping Errors, Up: Edebug + +22.4.8 Edebug Views +------------------- + +The following Edebug commands let you view aspects of the buffer and +window status that obtained before entry to Edebug. + +`v' + View the outside window configuration (`edebug-view-outside'). + +`p' + Temporarily display the outside current buffer with point at its + outside position (`edebug-bounce-point'). If prefix arg is + supplied, sit for that many seconds instead. + +`w' + Move point back to the current stop point (`edebug-where') in the + source code buffer. Also, if you use this command in another + window displaying the same buffer, this window will be used + instead to display the buffer in the future. + +`W' + Toggle the `edebug-save-windows' variable which indicates whether + the outside window configuration is saved and restored + (`edebug-toggle-save-windows'). Also, each time it is toggled on, + make the outside window configuration the same as the current + window configuration. + + With a prefix argument, `edebug-toggle-save-windows' only toggles + saving and restoring of the selected window. To specify a window + that is not displaying the source code buffer, you must use + `C-xXW' from the global keymap. + + + You can view the outside window configuration with `v' or just +bounce to the current point in the current buffer with `p', even if it +is not normally displayed. After moving point, you may wish to pop +back to the stop point with `w' from a source code buffer. + + By using `W' twice, Edebug again saves and restores the outside +window configuration, but to the current configuration. This is a +convenient way to, for example, add another buffer to be displayed +whenever Edebug is active. However, the automatic redisplay of +`*edebug*' and `*edebug-trace*' may conflict with the buffers you wish +to see unless you have enough windows open. + + +File: lispref.info, Node: Edebug Eval, Next: Eval List, Prev: Edebug Views, Up: Edebug + +22.4.9 Evaluation +----------------- + +While within Edebug, you can evaluate expressions "as if" Edebug were +not running. Edebug tries to be invisible to the expression's +evaluation and printing. Evaluation of expressions that cause side +effects will work as expected except for things that Edebug explicitly +saves and restores. See *Note The Outside Context:: for details on this +process. Also see *Note Reading in Edebug:: and *Note Printing in +Edebug:: for topics related to evaluation. + +`e EXP ' + Evaluate expression EXP in the context outside of Edebug + (`edebug-eval-expression'). In other words, Edebug tries to avoid + altering the effect of EXP. + +`M- EXP ' + Evaluate expression EXP in the context of Edebug itself. + +`C-x C-e' + Evaluate the expression before point, in the context outside of + Edebug (`edebug-eval-last-sexp'). + + Edebug supports evaluation of expressions containing references to +lexically bound symbols created by the following constructs in `cl.el' +(version 2.03 or later): `lexical-let', `macrolet', and +`symbol-macrolet'. + + +File: lispref.info, Node: Eval List, Next: Reading in Edebug, Prev: Edebug Eval, Up: Edebug + +22.4.10 Evaluation List Buffer +------------------------------ + +You can use the "evaluation list buffer", called `*edebug*', to +evaluate expressions interactively. You can also set up the +"evaluation list" of expressions to be evaluated automatically each +time Edebug updates the display. + +`E' + Switch to the evaluation list buffer `*edebug*' + (`edebug-visit-eval-list'). + + In the `*edebug*' buffer you can use the commands of Lisp +Interaction as well as these special commands: + +`LFD' + Evaluate the expression before point, in the outside context, and + insert the value in the buffer (`edebug-eval-print-last-sexp'). + +`C-x C-e' + Evaluate the expression before point, in the context outside of + Edebug (`edebug-eval-last-sexp'). + +`C-c C-u' + Build a new evaluation list from the first expression of each + group, reevaluate and redisplay (`edebug-update-eval-list'). + Groups are separated by comment lines. + +`C-c C-d' + Delete the evaluation list group that point is in + (`edebug-delete-eval-item'). + +`C-c C-w' + Switch back to the source code buffer at the current stop point + (`edebug-where'). + + You can evaluate expressions in the evaluation list window with +`LFD' or `C-x C-e', just as you would in `*scratch*'; but they are +evaluated in the context outside of Edebug. + + The expressions you enter interactively (and their results) are lost +when you continue execution unless you add them to the evaluation list +with `C-c C-u'. This command builds a new list from the first +expression of each "evaluation list group". Groups are separated by +comment lines. Be careful not to add expressions that execute +instrumented code otherwise an infinite loop will result. + + When the evaluation list is redisplayed, each expression is displayed +followed by the result of evaluating it, and a comment line. If an +error occurs during an evaluation, the error message is displayed in a +string as if it were the result. Therefore expressions that, for +example, use variables not currently valid do not interrupt your +debugging. + + Here is an example of what the evaluation list window looks like +after several expressions have been added to it: + + (current-buffer) + # + ;--------------------------------------------------------------- + (selected-window) + # + ;--------------------------------------------------------------- + (point) + 196 + ;--------------------------------------------------------------- + bad-var + "Symbol's value as variable is void: bad-var" + ;--------------------------------------------------------------- + (recursion-depth) + 0 + ;--------------------------------------------------------------- + this-command + eval-last-sexp + ;--------------------------------------------------------------- + + To delete a group, move point into it and type `C-c C-d', or simply +delete the text for the group and update the evaluation list with `C-c +C-u'. When you add a new group, be sure it is separated from its +neighbors by a comment line. + + After selecting `*edebug*', you can return to the source code buffer +with `C-c C-w'. The `*edebug*' buffer is killed when you continue +execution, and recreated next time it is needed. + + +File: lispref.info, Node: Reading in Edebug, Next: Printing in Edebug, Prev: Eval List, Up: Edebug + +22.4.11 Reading in Edebug +------------------------- + +To instrument a form, Edebug first reads the whole form. Edebug +replaces the standard Lisp Reader with its own reader that remembers the +positions of expressions. This reader is used by the Edebug +replacements for `eval-region', `eval-defun', `eval-buffer', and +`eval-current-buffer'. + + Another package, `cl-read.el', replaces the standard reader with one +that understands Common Lisp reader macros. If you use that package, +Edebug will automatically load `edebug-cl-read.el' to provide +corresponding reader macros that remember positions of expressions. If +you define new reader macros, you will have to define similar reader +macros for Edebug. + + +File: lispref.info, Node: Printing in Edebug, Next: Tracing, Prev: Reading in Edebug, Up: Edebug + +22.4.12 Printing in Edebug +-------------------------- + +If the result of an expression in your program contains a circular +reference, you may get an error when Edebug attempts to print it. You +can set `print-length' to a non-zero value to limit the print length of +lists (the number of cdrs), and in Emacs 19, set `print-level' to a +non-zero value to limit the print depth of lists. But you can print +such circular structures and structures that share elements more +informatively by using the `cust-print' package. + + To load `cust-print' and activate custom printing only for Edebug, +simply use the command `M-x edebug-install-custom-print'. To restore +the standard print functions, use `M-x edebug-uninstall-custom-print'. +You can also activate custom printing for printing in any Lisp code; +see the package for details. + + Here is an example of code that creates a circular structure: + + (progn + (edebug-install-custom-print) + (setq a '(x y)) + (setcar a a)) + + Edebug will print the result of the `setcar' as `Result: #1=(#1# +y)'. The `#1=' notation names the structure that follows it, and the +`#1#' notation references the previously named structure. This +notation is used for any shared elements of lists or vectors. + + Independent of whether `cust-print' is active, while printing +results Edebug binds `print-length', `print-level', and `print-circle' +to `edebug-print-length' (`50'), `edebug-print-level' (`50'), and +`edebug-print-circle' (`t') respectively, if these values are +non-`nil'. Also, `print-readably' is bound to `nil' since some objects +simply cannot be printed readably. + + +File: lispref.info, Node: Tracing, Next: Coverage Testing, Prev: Printing in Edebug, Up: Edebug + +22.4.13 Tracing +--------------- + +In addition to automatic stepping through source code, which is also +called _tracing_ (see *Note Edebug Execution Modes::), Edebug can +produce a traditional trace listing of execution in a separate buffer, +`*edebug-trace*'. + + If the variable `edebug-trace' is non-`nil', each function entry and +exit adds lines to the trace buffer. On function entry, Edebug prints +`::::{' followed by the function name and argument values. On function +exit, Edebug prints `::::}' followed by the function name and result of +the function. The number of `:'s is computed from the recursion depth. +The balanced braces in the trace buffer can be used to find the +matching beginning or end of function calls. These displays may be +customized by replacing the functions `edebug-print-trace-before' and +`edebug-print-trace-after', which take an arbitrary message string to +print. + + The macro `edebug-tracing' provides tracing similar to function +enter and exit tracing, but for arbitrary expressions. This macro +should be explicitly inserted by you around expressions you wish to +trace the execution of. The first argument is a message string +(evaluated), and the rest are expressions to evaluate. The result of +the last expression is returned. + + Finally, you can insert arbitrary strings into the trace buffer with +explicit calls to `edebug-trace'. The arguments of this function are +the same as for `message', but a newline is always inserted after each +string printed in this way. + + `edebug-tracing' and `edebug-trace' insert lines in the trace buffer +even if Edebug is not active. Every time the trace buffer is added to, +the window is scrolled to show the last lines inserted. (There may be +some display problems if you use tracing along with the evaluation +list.) + + +File: lispref.info, Node: Coverage Testing, Next: The Outside Context, Prev: Tracing, Up: Edebug + +22.4.14 Coverage Testing +------------------------ + +Edebug provides a rudimentary coverage tester and display of execution +frequency. Frequency counts are always accumulated, both before and +after evaluation of each instrumented expression, even if the execution +mode is `Go-nonstop'. Coverage testing is only done if the option +`edebug-test-coverage' is non-`nil' because this is relatively +expensive. Both data sets are displayed by `M-x +edebug-display-freq-count'. + + -- Command: edebug-display-freq-count + Display the frequency count data for each line of the current + definition. The frequency counts are inserted as comment lines + after each line, and you can undo all insertions with one `undo' + command. The counts are inserted starting under the `(' before an + expression or the `)' after an expression, or on the last char of + a symbol. The counts are only displayed when they differ from + previous counts on the same line. + + If coverage is being tested, whenever all known results of an + expression are `eq', the char `=' will be appended after the count + for that expression. Note that this is always the case for an + expression only evaluated once. + + To clear the frequency count and coverage data for a definition, + reinstrument it. + + + For example, after evaluating `(fac 5)' with an embedded breakpoint, +and setting `edebug-test-coverage' to `t', when the breakpoint is +reached, the frequency data is looks like this: + + (defun fac (n) + (if (= n 0) (edebug)) + ;#6 1 0 =5 + (if (< 0 n) + ;#5 = + (* n (fac (1- n))) + ;# 5 0 + 1)) + ;# 0 + + The comment lines show that `fac' has been called 6 times. The +first `if' statement has returned 5 times with the same result each +time, and the same is true for the condition on the second `if'. The +recursive call of `fac' has not returned at all. + + +File: lispref.info, Node: The Outside Context, Next: Instrumenting Macro Calls, Prev: Coverage Testing, Up: Edebug + +22.4.15 The Outside Context +--------------------------- + +Edebug tries to be transparent to the program you are debugging. In +addition, most evaluations you do within Edebug (see *Note Edebug +Eval::) occur in the same outside context which is temporarily restored +for the evaluation. But Edebug is not completely successful and this +section explains precisely how it fails. Edebug operation unavoidably +alters some data in XEmacs, and this can interfere with debugging +certain programs. Also notice that Edebug's protection against change +of outside data means that any side effects _intended_ by the user in +the course of debugging will be defeated. + +* Menu: + +* Checking Whether to Stop:: When Edebug decides what to do. +* Edebug Display Update:: When Edebug updates the display. +* Edebug Recursive Edit:: When Edebug stops execution. + + +File: lispref.info, Node: Checking Whether to Stop, Next: Edebug Display Update, Up: The Outside Context + +22.4.15.1 Checking Whether to Stop +.................................. + +Whenever Edebug is entered just to think about whether to take some +action, it needs to save and restore certain data. + + * `max-lisp-eval-depth' and `max-specpdl-size' are both incremented + one time to reduce Edebug's impact on the stack. You could, + however, still run out of stack space when using Edebug. + + * The state of keyboard macro execution is saved and restored. While + Edebug is active, `executing-macro' is bound to + `edebug-continue-kbd-macro'. + + + +File: lispref.info, Node: Edebug Display Update, Next: Edebug Recursive Edit, Prev: Checking Whether to Stop, Up: The Outside Context + +22.4.15.2 Edebug Display Update +............................... + +When Edebug needs to display something (e.g., in trace mode), it saves +the current window configuration from "outside" Edebug. When you exit +Edebug (by continuing the program), it restores the previous window +configuration. + + XEmacs redisplays only when it pauses. Usually, when you continue +execution, the program comes back into Edebug at a breakpoint or after +stepping without pausing or reading input in between. In such cases, +XEmacs never gets a chance to redisplay the "outside" configuration. +What you see is the same window configuration as the last time Edebug +was active, with no interruption. + + Entry to Edebug for displaying something also saves and restores the +following data, but some of these are deliberately not restored if an +error or quit signal occurs. + + * Which buffer is current, and where point and mark are in the + current buffer are saved and restored. + + * The Edebug Display Update, is saved and restored if + `edebug-save-windows' is non-`nil'. It is not restored on error + or quit, but the outside selected window _is_ reselected even on + error or quit in case a `save-excursion' is active. If the value + of `edebug-save-windows' is a list, only the listed windows are + saved and restored. + + The window start and horizontal scrolling of the source code + buffer are not restored, however, so that the display remains + coherent. + + * The value of point in each displayed buffer is saved and restored + if `edebug-save-displayed-buffer-points' is non-`nil'. + + * The variables `overlay-arrow-position' and `overlay-arrow-string' + are saved and restored. So you can safely invoke Edebug from the + recursive edit elsewhere in the same buffer. + + * `cursor-in-echo-area' is locally bound to `nil' so that the cursor + shows up in the window. + + + +File: lispref.info, Node: Edebug Recursive Edit, Prev: Edebug Display Update, Up: The Outside Context + +22.4.15.3 Edebug Recursive Edit +............................... + +When Edebug is entered and actually reads commands from the user, it +saves (and later restores) these additional data: + + * The current match data, for whichever buffer was current. + + * `last-command', `this-command', `last-command-char', + `last-input-char', `last-input-event', `last-command-event', + `last-event-frame', `last-nonmenu-event', and `track-mouse' . + Commands used within Edebug do not affect these variables outside + of Edebug. + + The key sequence returned by `this-command-keys' is changed by + executing commands within Edebug and there is no way to reset the + key sequence from Lisp. + + For Emacs 18, Edebug cannot save and restore the value of + `unread-command-char'. Entering Edebug while this variable has a + nontrivial value can interfere with execution of the program you + are debugging. + + * Complex commands executed while in Edebug are added to the variable + `command-history'. In rare cases this can alter execution. + + * Within Edebug, the recursion depth appears one deeper than the + recursion depth outside Edebug. This is not true of the + automatically updated evaluation list window. + + * `standard-output' and `standard-input' are bound to `nil' by the + `recursive-edit', but Edebug temporarily restores them during + evaluations. + + * The state of keyboard macro definition is saved and restored. + While Edebug is active, `defining-kbd-macro' is bound to + `edebug-continue-kbd-macro'. + + + +File: lispref.info, Node: Instrumenting Macro Calls, Next: Edebug Options, Prev: The Outside Context, Up: Edebug + +22.4.16 Instrumenting Macro Calls +--------------------------------- + +When Edebug instruments an expression that calls a Lisp macro, it needs +additional advice to do the job properly. This is because there is no +way to tell which subexpressions of the macro call may be evaluated. +(Evaluation may occur explicitly in the macro body, or when the +resulting expansion is evaluated, or any time later.) You must explain +the format of macro call arguments by using `def-edebug-spec' to define +an "Edebug specification" for each macro. + + -- Macro: def-edebug-spec macro specification + Specify which expressions of a call to macro MACRO are forms to be + evaluated. For simple macros, the SPECIFICATION often looks very + similar to the formal argument list of the macro definition, but + specifications are much more general than macro arguments. + + The MACRO argument may actually be any symbol, not just a macro + name. + + Unless you are using Emacs 19 or XEmacs, this macro is only defined + in Edebug, so you may want to use the following which is + equivalent: `(put 'MACRO 'edebug-form-spec 'SPECIFICATION)' + + Here is a simple example that defines the specification for the +`for' macro described in the XEmacs Lisp Reference Manual, followed by +an alternative, equivalent specification. + + (def-edebug-spec for + (symbolp "from" form "to" form "do" &rest form)) + + (def-edebug-spec for + (symbolp ['from form] ['to form] ['do body])) + + Here is a table of the possibilities for SPECIFICATION and how each +directs processing of arguments. + +*`t' + All arguments are instrumented for evaluation. + +*`0' + None of the arguments is instrumented. + +*a symbol + The symbol must have an Edebug specification which is used instead. + This indirection is repeated until another kind of specification is + found. This allows you to inherit the specification for another + macro. + +*a list + The elements of the list describe the types of the arguments of a + calling form. The possible elements of a specification list are + described in the following sections. + +* Menu: + +* Specification List:: How to specify complex patterns of evaluation. +* Backtracking:: What Edebug does when matching fails. +* Debugging Backquote:: Debugging Backquote +* Specification Examples:: To help understand specifications. + + +File: lispref.info, Node: Specification List, Next: Backtracking, Up: Instrumenting Macro Calls + +22.4.16.1 Specification List +............................ + +A "specification list" is required for an Edebug specification if some +arguments of a macro call are evaluated while others are not. Some +elements in a specification list match one or more arguments, but others +modify the processing of all following elements. The latter, called +"keyword specifications", are symbols beginning with ``&'' (e.g. +`&optional'). + + A specification list may contain sublists which match arguments that +are themselves lists, or it may contain vectors used for grouping. +Sublists and groups thus subdivide the specification list into a +hierarchy of levels. Keyword specifications only apply to the +remainder of the sublist or group they are contained in and there is an +implicit grouping around a keyword specification and all following +elements in the sublist or group. + + If a specification list fails at some level, then backtracking may +be invoked to find some alternative at a higher level, or if no +alternatives remain, an error will be signaled. See *Note +Backtracking:: for more details. + + Edebug specifications provide at least the power of regular +expression matching. Some context-free constructs are also supported: +the matching of sublists with balanced parentheses, recursive +processing of forms, and recursion via indirect specifications. + + Each element of a specification list may be one of the following, +with the corresponding type of argument: + +`sexp' + A single unevaluated expression. + +`form' + A single evaluated expression, which is instrumented. + +`place' + A place as in the Common Lisp `setf' place argument. It will be + instrumented just like a form, but the macro is expected to strip + the instrumentation. Two functions, `edebug-unwrap' and + `edebug-unwrap*', are provided to strip the instrumentation one + level or recursively at all levels. + +`body' + Short for `&rest form'. See `&rest' below. + +`function-form' + A function form: either a quoted function symbol, a quoted lambda + expression, or a form (that should evaluate to a function symbol + or lambda expression). This is useful when function arguments + might be quoted with `quote' rather than `function' since the body + of a lambda expression will be instrumented either way. + +`lambda-expr' + An unquoted anonymous lambda expression. + +`&optional' + All following elements in the specification list are optional; as + soon as one does not match, Edebug stops matching at this level. + + To make just a few elements optional followed by non-optional + elements, use `[&optional SPECS...]'. To specify that several + elements should all succeed together, use `&optional [SPECS...]'. + See the `defun' example below. + +`&rest' + All following elements in the specification list are repeated zero + or more times. All the elements need not match in the last + repetition, however. + + To repeat only a few elements, use `[&rest SPECS...]'. To specify + all elements must match on every repetition, use `&rest + [SPECS...]'. + +`&or' + Each of the following elements in the specification list is an + alternative, processed left to right until one matches. One of the + alternatives must match otherwise the `&or' specification fails. + + Each list element following `&or' is a single alternative even if + it is a keyword specification. (This breaks the implicit grouping + rule.) To group two or more list elements as a single + alternative, enclose them in `[...]'. + +`¬' + Each of the following elements is matched as alternatives as if by + using `&or', but if any of them match, the specification fails. + If none of them match, nothing is matched, but the `¬' + specification succeeds. + +`&define' + Indicates that the specification is for a defining form. The + defining form itself is not instrumented (i.e. Edebug does not + stop before and after the defining form), but forms inside it + typically will be instrumented. The `&define' keyword should be + the first element in a list specification. + + Additional specifications that may only appear after `&define' are + described here. See the `defun' example below. + + `name' + The argument, a symbol, is the name of the defining form. + But a defining form need not be named at all, in which case a + unique name will be created for it. + + The `name' specification may be used more than once in the + specification and each subsequent use will append the + corresponding symbol argument to the previous name with ``@'' + between them. This is useful for generating unique but + meaningful names for definitions such as `defadvice' and + `defmethod'. + + `:name' + The element following `:name' should be a symbol; it is used + as an additional name component for the definition. This is + useful to add a unique, static component to the name of the + definition. It may be used more than once. No argument is + matched. + + `arg' + The argument, a symbol, is the name of an argument of the + defining form. However, lambda list keywords (symbols + starting with ``&'') are not allowed. See `lambda-list' and + the example below. + + `lambda-list' + This matches the whole argument list of an XEmacs Lisp lambda + expression, which is a list of symbols and the keywords + `&optional' and `&rest' + + `def-body' + The argument is the body of code in a definition. This is + like `body', described above, but a definition body must be + instrumented with a different Edebug call that looks up + information associated with the definition. Use `def-body' + for the highest level list of forms within the definition. + + `def-form' + The argument is a single, highest-level form in a definition. + This is like `def-body', except use this to match a single + form rather than a list of forms. As a special case, + `def-form' also means that tracing information is not output + when the form is executed. See the `interactive' example + below. + + +`nil' + This is successful when there are no more arguments to match at the + current argument list level; otherwise it fails. See sublist + specifications and the backquote example below. + +`gate' + No argument is matched but backtracking through the gate is + disabled while matching the remainder of the specifications at + this level. This is primarily used to generate more specific + syntax error messages. See *Note Backtracking:: for more details. + Also see the `let' example below. + +`OTHER-SYMBOL' + Any other symbol in a specification list may be a predicate or an + indirect specification. + + If the symbol has an Edebug specification, this "indirect + specification" should be either a list specification that is used + in place of the symbol, or a function that is called to process the + arguments. The specification may be defined with `def-edebug-spec' + just as for macros. See the `defun' example below. + + Otherwise, the symbol should be a predicate. The predicate is + called with the argument and the specification fails if the + predicate fails. The argument is not instrumented. + + Predicates that may be used include: `symbolp', `integerp', + `stringp', `vectorp', `atom' (which matches a number, string, + symbol, or vector), `keywordp', and `lambda-list-keywordp'. The + last two, defined in `edebug.el', test whether the argument is a + symbol starting with ``:'' and ``&'' respectively. + +`[ELEMENTS...]' + Rather than matching a vector argument, a vector treats the + ELEMENTS as a single "group specification". + +`"STRING"' + The argument should be a symbol named STRING. This specification + is equivalent to the quoted symbol, `'SYMBOL', where the name of + SYMBOL is the STRING, but the string form is preferred. + +`'SYMBOL or (quote SYMBOL)' + The argument should be the symbol SYMBOL. But use a string + specification instead. + +`(vector ELEMENTS...)' + The argument should be a vector whose elements must match the + ELEMENTS in the specification. See the backquote example below. + +`(ELEMENTS...)' + Any other list is a "sublist specification" and the argument must + be a list whose elements match the specification ELEMENTS. + + A sublist specification may be a dotted list and the corresponding + list argument may then be a dotted list. Alternatively, the last + cdr of a dotted list specification may be another sublist + specification (via a grouping or an indirect specification, e.g. + `(spec . [(more specs...)])') whose elements match the non-dotted + list arguments. This is useful in recursive specifications such + as in the backquote example below. Also see the description of a + `nil' specification above for terminating such recursion. + + Note that a sublist specification of the form `(specs . nil)' + means the same as `(specs)', and `(specs . + (sublist-elements...))' means the same as `(specs + sublist-elements...)'. + + + +File: lispref.info, Node: Backtracking, Next: Debugging Backquote, Prev: Specification List, Up: Instrumenting Macro Calls + +22.4.16.2 Backtracking +...................... + +If a specification fails to match at some point, this does not +necessarily mean a syntax error will be signaled; instead, +"backtracking" will take place until all alternatives have been +exhausted. Eventually every element of the argument list must be +matched by some element in the specification, and every required element +in the specification must match some argument. + + Backtracking is disabled for the remainder of a sublist or group when +certain conditions occur, described below. Backtracking is reenabled +when a new alternative is established by `&optional', `&rest', or +`&or'. It is also reenabled initially when processing a sublist or +group specification or an indirect specification. + + You might want to disable backtracking to commit to some alternative +so that Edebug can provide a more specific syntax error message. +Normally, if no alternative matches, Edebug reports that none matched, +but if one alternative is committed to, Edebug can report how it failed +to match. + + First, backtracking is disabled while matching any of the form +specifications (i.e. `form', `body', `def-form', and `def-body'). +These specifications will match any form so any error must be in the +form itself rather than at a higher level. + + Second, backtracking is disabled after successfully matching a quoted +symbol or string specification, since this usually indicates a +recognized construct. If you have a set of alternative constructs that +all begin with the same symbol, you can usually work around this +constraint by factoring the symbol out of the alternatives, e.g., +`["foo" &or [first case] [second case] ...]'. + + Third, backtracking may be explicitly disabled by using the `gate' +specification. This is useful when you know that no higher +alternatives may apply. + + +File: lispref.info, Node: Debugging Backquote, Next: Specification Examples, Prev: Backtracking, Up: Instrumenting Macro Calls + +22.4.16.3 Debugging Backquote +............................. + +Backquote (``') is a macro that results in an expression that may or +may not be evaluated. It is often used to simplify the definition of a +macro to return an expression that is evaluated, but Edebug does not +know when this is the case. However, the forms inside unquotes (`,' and +`,@') are evaluated and Edebug instruments them. + + Nested backquotes are supported by Edebug, but there is a limit on +the support of quotes inside of backquotes. Quoted forms (with `'') +are not normally evaluated, but if the quoted form appears immediately +within `,' and `,@' forms, Edebug treats this as a backquoted form at +the next higher level (even if there is not a next higher level - this +is difficult to fix). + + If the backquoted forms happen to be code intended to be evaluated, +you can have Edebug instrument them by using `edebug-`' instead of the +regular ``'. Unquoted forms can always appear inside `edebug-`' +anywhere a form is normally allowed. But `(, FORM)' may be used in two +other places specially recognized by Edebug: wherever a predicate +specification would match, and at the head of a list form in place of a +function name or lambda expression. The FORM inside a spliced unquote, +`(,@ FORM)', will be wrapped, but the unquote form itself will not be +wrapped since this would interfere with the splicing. + + There is one other complication with using `edebug-`'. If the +`edebug-`' call is in a macro and the macro may be called from code +that is also instrumented, and if unquoted forms contain any macro +arguments bound to instrumented forms, then you should modify the +specification for the macro as follows: the specifications for those +arguments must use `def-form' instead of `form'. (This is to +reestablish the Edebugging context for those external forms.) + + For example, the `for' macro (*note Problems with Macros: ()Problems +with Macros.) is shown here but with `edebug-`' substituted for regular +``'. + + (defmacro inc (var) + (list 'setq var (list '1+ var))) + + (defmacro for (var from init to final do &rest body) + (let ((tempvar (make-symbol "max"))) + (edebug-` (let (((, var) (, init)) + ((, tempvar) (, final))) + (while (<= (, var) (, tempvar)) + (, body) + (inc (, var))))))) + + Here is the corresponding modified Edebug specification and some code +that calls the macro: + + (def-edebug-spec for + (symbolp "from" def-form "to" def-form "do" &rest def-form)) + + (let ((n 5)) + (for i from n to (* n (+ n 1)) do + (message "%s" i))) + + After instrumenting the `for' macro and the macro call, Edebug first +steps to the beginning of the macro call, then into the macro body, +then through each of the unquoted expressions in the backquote showing +the expressions that will be embedded in the backquote form. Then when +the macro expansion is evaluated, Edebug will step through the `let' +form and each time it gets to an unquoted form, it will jump back to an +argument of the macro call to step through that expression. Finally +stepping will continue after the macro call. Even more convoluted +execution paths may result when using anonymous functions. + + When the result of an expression is an instrumented expression, it is +difficult to see the expression inside the instrumentation. So you may +want to set the option `edebug-unwrap-results' to a non-`nil' value +while debugging such expressions, but it would slow Edebug down to +always do this. + + +File: lispref.info, Node: Specification Examples, Prev: Debugging Backquote, Up: Instrumenting Macro Calls + +22.4.16.4 Specification Examples +................................ + +Here we provide several examples of Edebug specifications to show many +of its capabilities. + + A `let' special form has a sequence of bindings and a body. Each of +the bindings is either a symbol or a sublist with a symbol and optional +value. In the specification below, notice the `gate' inside of the +sublist to prevent backtracking. + + (def-edebug-spec let + ((&rest + &or symbolp (gate symbolp &optional form)) + body)) + + Edebug uses the following specifications for `defun' and `defmacro' +and the associated argument list and `interactive' specifications. It +is necessary to handle the expression argument of an interactive form +specially since it is actually evaluated outside of the function body. + + (def-edebug-spec defmacro defun) ; Indirect ref to `defun' spec + (def-edebug-spec defun + (&define name lambda-list + [&optional stringp] ; Match the doc string, if present. + [&optional ("interactive" interactive)] + def-body)) + + (def-edebug-spec lambda-list + (([&rest arg] + [&optional ["&optional" arg &rest arg]] + &optional ["&rest" arg] + ))) + + (def-edebug-spec interactive + (&optional &or stringp def-form)) ; Notice: `def-form' + + The specification for backquote below illustrates how to match +dotted lists and use `nil' to terminate recursion. It also illustrates +how components of a vector may be matched. (The actual specification +provided by Edebug does not support dotted lists because doing so +causes very deep recursion that could fail.) + + (def-edebug-spec ` (backquote-form)) ;; alias just for clarity + + (def-edebug-spec backquote-form + (&or ([&or "," ",@"] &or ("quote" backquote-form) form) + (backquote-form . [&or nil backquote-form]) + (vector &rest backquote-form) + sexp)) + + +File: lispref.info, Node: Edebug Options, Prev: Instrumenting Macro Calls, Up: Edebug + +22.4.17 Edebug Options +---------------------- + +These options affect the behavior of Edebug: + + -- User Option: edebug-setup-hook + Functions to call before Edebug is used. Each time it is set to a + new value, Edebug will call those functions once and then + `edebug-setup-hook' is reset to `nil'. You could use this to load + up Edebug specifications associated with a package you are using + but only when you also use Edebug. See *Note Instrumenting::. + + -- User Option: edebug-all-defs + If non-`nil', normal evaluation of any defining forms (e.g. + `defun' and `defmacro') will instrument them for Edebug. This + applies to `eval-defun', `eval-region', and `eval-current-buffer'. + + Use the command `M-x edebug-all-defs' to toggle the value of this + variable. You may want to make this variable local to each buffer + by calling `(make-local-variable 'edebug-all-defs)' in your + `emacs-lisp-mode-hook'. See *Note Instrumenting::. + + -- User Option: edebug-all-forms + If non-`nil', normal evaluation of any forms by `eval-defun', + `eval-region', and `eval-current-buffer' will instrument them for + Edebug. + + Use the command `M-x edebug-all-forms' to toggle the value of this + option. See *Note Instrumenting::. + + -- User Option: edebug-save-windows + If non-`nil', save and restore window configuration on Edebug + calls. It takes some time to do this, so if your program does not + care what happens to data about windows, you may want to set this + variable to `nil'. + + If the value is a list, only the listed windows are saved and + restored. + + `M-x edebug-toggle-save-windows' may be used to change this + variable. This command is bound to `W' in source code buffers. + See *Note Edebug Display Update::. + + -- User Option: edebug-save-displayed-buffer-points + If non-`nil', save and restore point in all displayed buffers. + This is necessary if you are debugging code that changes the point + of a buffer which is displayed in a non-selected window. If + Edebug or the user then selects the window, the buffer's point + will be changed to the window's point. + + This is an expensive operation since it visits each window and + therefore each displayed buffer twice for each Edebug activation, + so it is best to avoid it if you can. See *Note Edebug Display + Update::. + + -- User Option: edebug-initial-mode + If this variable is non-`nil', it specifies the initial execution + mode for Edebug when it is first activated. Possible values are + `step', `next', `go', `Go-nonstop', `trace', `Trace-fast', + `continue', and `Continue-fast'. + + The default value is `step'. See *Note Edebug Execution Modes::. + + -- User Option: edebug-trace + Non-`nil' means display a trace of function entry and exit. + Tracing output is displayed in a buffer named `*edebug-trace*', one + function entry or exit per line, indented by the recursion level. + + The default value is `nil'. + + Also see `edebug-tracing'. See *Note Tracing::. + + -- User Option: edebug-test-coverage + If non-`nil', Edebug tests coverage of all expressions debugged. + This is done by comparing the result of each expression with the + previous result. Coverage is considered OK if two different + results are found. So to sufficiently test the coverage of your + code, try to execute it under conditions that evaluate all + expressions more than once, and produce different results for each + expression. + + Use `M-x edebug-display-freq-count' to display the frequency count + and coverage information for a definition. See *Note Coverage + Testing::. + + -- User Option: edebug-continue-kbd-macro + If non-`nil', continue defining or executing any keyboard macro + that is executing outside of Edebug. Use this with caution since + it is not debugged. See *Note Edebug Execution Modes::. + + -- User Option: edebug-print-length + If non-`nil', bind `print-length' to this while printing results + in Edebug. The default value is `50'. See *Note Printing in + Edebug::. + + -- User Option: edebug-print-level + If non-`nil', bind `print-level' to this while printing results in + Edebug. The default value is `50'. + + -- User Option: edebug-print-circle + If non-`nil', bind `print-circle' to this while printing results + in Edebug. The default value is `nil'. + + -- User Option: edebug-on-error + `debug-on-error' is bound to this while Edebug is active. See + *Note Trapping Errors::. + + -- User Option: edebug-on-quit + `debug-on-quit' is bound to this while Edebug is active. See + *Note Trapping Errors::. + + -- User Option: edebug-unwrap-results + Non-`nil' if Edebug should unwrap results of expressions. This is + useful when debugging macros where the results of expressions are + instrumented expressions. But don't do this when results might be + circular or an infinite loop will result. See *Note Debugging + Backquote::. + + -- User Option: edebug-global-break-condition + If non-`nil', an expression to test for at every stop point. If + the result is non-`nil', then break. Errors are ignored. See + *Note Global Break Condition::. + + +File: lispref.info, Node: Read and Print, Next: Minibuffers, Prev: Debugging, Up: Top + +23 Reading and Printing Lisp Objects +************************************ + +"Printing" and "reading" are the operations of converting Lisp objects +to textual form and vice versa. They use the printed representations +and read syntax described in *Note Lisp Data Types::. + + This chapter describes the Lisp functions for reading and printing. +It also describes "streams", which specify where to get the text (if +reading) or where to put it (if printing). + +* Menu: + +* Streams Intro:: Overview of streams, reading and printing. +* Input Streams:: Various data types that can be used as input streams. +* Input Functions:: Functions to read Lisp objects from text. +* Output Streams:: Various data types that can be used as output streams. +* Output Functions:: Functions to print Lisp objects as text. +* Output Variables:: Variables that control what the printing functions do. + + +File: lispref.info, Node: Streams Intro, Next: Input Streams, Up: Read and Print + +23.1 Introduction to Reading and Printing +========================================= + +"Reading" a Lisp object means parsing a Lisp expression in textual form +and producing a corresponding Lisp object. This is how Lisp programs +get into Lisp from files of Lisp code. We call the text the "read +syntax" of the object. For example, the text `(a . 5)' is the read +syntax for a cons cell whose CAR is `a' and whose CDR is the number 5. + + "Printing" a Lisp object means producing text that represents that +object--converting the object to its printed representation. Printing +the cons cell described above produces the text `(a . 5)'. + + Reading and printing are more or less inverse operations: printing +the object that results from reading a given piece of text often +produces the same text, and reading the text that results from printing +an object usually produces a similar-looking object. For example, +printing the symbol `foo' produces the text `foo', and reading that text +returns the symbol `foo'. Printing a list whose elements are `a' and +`b' produces the text `(a b)', and reading that text produces a list +(but not the same list) with elements `a' and `b'. + + However, these two operations are not precisely inverses. There are +three kinds of exceptions: + + * Printing can produce text that cannot be read. For example, + buffers, windows, frames, subprocesses and markers print into text + that starts with `#'; if you try to read this text, you get an + error. There is no way to read those data types. + + * One object can have multiple textual representations. For example, + `1' and `01' represent the same integer, and `(a b)' and `(a . + (b))' represent the same list. Reading will accept any of the + alternatives, but printing must choose one of them. + + * Comments can appear at certain points in the middle of an object's + read sequence without affecting the result of reading it. + + +File: lispref.info, Node: Input Streams, Next: Input Functions, Prev: Streams Intro, Up: Read and Print + +23.2 Input Streams +================== + +Most of the Lisp functions for reading text take an "input stream" as +an argument. The input stream specifies where or how to get the +characters of the text to be read. Here are the possible types of input +stream: + +BUFFER + The input characters are read from BUFFER, starting with the + character directly after point. Point advances as characters are + read. + +MARKER + The input characters are read from the buffer that MARKER is in, + starting with the character directly after the marker. The marker + position advances as characters are read. The value of point in + the buffer has no effect when the stream is a marker. + +STRING + The input characters are taken from STRING, starting at the first + character in the string and using as many characters as required. + +FUNCTION + The input characters are generated by FUNCTION, one character per + call. Normally FUNCTION is called with no arguments, and should + return a character. + + Occasionally FUNCTION is called with one argument (always a + character). When that happens, FUNCTION should save the argument + and arrange to return it on the next call. This is called + "unreading" the character; it happens when the Lisp reader reads + one character too many and wants to "put it back where it came + from". + +`t' + `t' used as a stream means that the input is read from the + minibuffer. In fact, the minibuffer is invoked once and the text + given by the user is made into a string that is then used as the + input stream. + +`nil' + `nil' supplied as an input stream means to use the value of + `standard-input' instead; that value is the "default input + stream", and must be a non-`nil' input stream. + +SYMBOL + A symbol as input stream is equivalent to the symbol's function + definition (if any). + + Here is an example of reading from a stream that is a buffer, showing +where point is located before and after: + + ---------- Buffer: foo ---------- + This-!- is the contents of foo. + ---------- Buffer: foo ---------- + + (read (get-buffer "foo")) + => is + (read (get-buffer "foo")) + => the + + ---------- Buffer: foo ---------- + This is the-!- contents of foo. + ---------- Buffer: foo ---------- + +Note that the first read skips a space. Reading skips any amount of +whitespace preceding the significant text. + + In Emacs 18, reading a symbol discarded the delimiter terminating the +symbol. Thus, point would end up at the beginning of `contents' rather +than after `the'. The Emacs 19 behavior is superior because it +correctly handles input such as `bar(foo)', where the open-parenthesis +that ends one object is needed as the beginning of another object. + + Here is an example of reading from a stream that is a marker, +initially positioned at the beginning of the buffer shown. The value +read is the symbol `This'. + + + ---------- Buffer: foo ---------- + This is the contents of foo. + ---------- Buffer: foo ---------- + + (setq m (set-marker (make-marker) 1 (get-buffer "foo"))) + => # + (read m) + => This + m + => # ;; Before the first space. + + Here we read from the contents of a string: + + (read "(When in) the course") + => (When in) + + The following example reads from the minibuffer. The prompt is: +`Lisp expression: '. (That is always the prompt used when you read +from the stream `t'.) The user's input is shown following the prompt. + + (read t) + => 23 + ---------- Buffer: Minibuffer ---------- + Lisp expression: 23 + ---------- Buffer: Minibuffer ---------- + + Finally, here is an example of a stream that is a function, named +`useless-stream'. Before we use the stream, we initialize the variable +`useless-list' to a list of characters. Then each call to the function +`useless-stream' obtains the next character in the list or unreads a +character by adding it to the front of the list. + + (setq useless-list (append "XY()" nil)) + => (88 89 40 41) + + (defun useless-stream (&optional unread) + (if unread + (setq useless-list (cons unread useless-list)) + (prog1 (car useless-list) + (setq useless-list (cdr useless-list))))) + => useless-stream + +Now we read using the stream thus constructed: + + (read 'useless-stream) + => XY + + useless-list + => (40 41) + +Note that the open and close parentheses remains in the list. The Lisp +reader encountered the open parenthesis, decided that it ended the +input, and unread it. Another attempt to read from the stream at this +point would read `()' and return `nil'. + + +File: lispref.info, Node: Input Functions, Next: Output Streams, Prev: Input Streams, Up: Read and Print + +23.3 Input Functions +==================== + +This section describes the Lisp functions and variables that pertain to +reading. + + In the functions below, STREAM stands for an input stream (see the +previous section). If STREAM is `nil' or omitted, it defaults to the +value of `standard-input'. + + An `end-of-file' error is signaled if reading encounters an +unterminated list, vector, or string. + + -- Function: read &optional stream + This function reads one textual Lisp expression from STREAM, + returning it as a Lisp object. This is the basic Lisp input + function. + + -- Function: read-from-string string &optional start end + This function reads the first textual Lisp expression from the + text in STRING. It returns a cons cell whose CAR is that + expression, and whose CDR is an integer giving the position of the + next remaining character in the string (i.e., the first one not + read). + + If START is supplied, then reading begins at index START in the + string (where the first character is at index 0). If END is also + supplied, then reading stops just before that index, as if the rest + of the string were not there. + + For example: + + (read-from-string "(setq x 55) (setq y 5)") + => ((setq x 55) . 11) + (read-from-string "\"A short string\"") + => ("A short string" . 16) + + ;; Read starting at the first character. + (read-from-string "(list 112)" 0) + => ((list 112) . 10) + ;; Read starting at the second character. + (read-from-string "(list 112)" 1) + => (list . 5) + ;; Read starting at the seventh character, + ;; and stopping at the ninth. + (read-from-string "(list 112)" 6 8) + => (11 . 8) + + -- Variable: standard-input + This variable holds the default input stream--the stream that + `read' uses when the STREAM argument is `nil'. + + +File: lispref.info, Node: Output Streams, Next: Output Functions, Prev: Input Functions, Up: Read and Print + +23.4 Output Streams +=================== + +An output stream specifies what to do with the characters produced by +printing. Most print functions accept an output stream as an optional +argument. Here are the possible types of output stream: + +BUFFER + The output characters are inserted into BUFFER at point. Point + advances as characters are inserted. + +MARKER + The output characters are inserted into the buffer that MARKER + points into, at the marker position. The marker position advances + as characters are inserted. The value of point in the buffer has + no effect on printing when the stream is a marker. + +FUNCTION + The output characters are passed to FUNCTION, which is responsible + for storing them away. It is called with a single character as + argument, as many times as there are characters to be output, and + is free to do anything at all with the characters it receives. + +`t' + The output characters are displayed in the echo area. + +`nil' + `nil' specified as an output stream means to the value of + `standard-output' instead; that value is the "default output + stream", and must be a non-`nil' output stream. + +SYMBOL + A symbol as output stream is equivalent to the symbol's function + definition (if any). + + Many of the valid output streams are also valid as input streams. +The difference between input and output streams is therefore mostly one +of how you use a Lisp object, not a distinction of types of object. + + Here is an example of a buffer used as an output stream. Point is +initially located as shown immediately before the `h' in `the'. At the +end, point is located directly before that same `h'. + + ---------- Buffer: foo ---------- + This is t-!-he contents of foo. + ---------- Buffer: foo ---------- + + (print "This is the output" (get-buffer "foo")) + => "This is the output" + + ---------- Buffer: foo ---------- + This is t + "This is the output" + -!-he contents of foo. + ---------- Buffer: foo ---------- + + Now we show a use of a marker as an output stream. Initially, the +marker is in buffer `foo', between the `t' and the `h' in the word +`the'. At the end, the marker has advanced over the inserted text so +that it remains positioned before the same `h'. Note that the location +of point, shown in the usual fashion, has no effect. + + ---------- Buffer: foo ---------- + "This is the -!-output" + ---------- Buffer: foo ---------- + + m + => # + + (print "More output for foo." m) + => "More output for foo." + + ---------- Buffer: foo ---------- + "This is t + "More output for foo." + he -!-output" + ---------- Buffer: foo ---------- + + m + => # + + The following example shows output to the echo area: + + (print "Echo Area output" t) + => "Echo Area output" + ---------- Echo Area ---------- + "Echo Area output" + ---------- Echo Area ---------- + + Finally, we show the use of a function as an output stream. The +function `eat-output' takes each character that it is given and conses +it onto the front of the list `last-output' (*note Building Lists::). +At the end, the list contains all the characters output, but in reverse +order. + + (setq last-output nil) + => nil + + (defun eat-output (c) + (setq last-output (cons c last-output))) + => eat-output + + (print "This is the output" 'eat-output) + => "This is the output" + + last-output + => (?\n ?\" ?t ?u ?p ?t ?u ?o ?\ ?e ?h ?t + ?\ ?s ?i ?\ ?s ?i ?h ?T ?\" ?\n) + +Now we can put the output in the proper order by reversing the list: + + (concat (nreverse last-output)) + => " + \"This is the output\" + " + +Calling `concat' converts the list to a string so you can see its +contents more clearly. + + +File: lispref.info, Node: Output Functions, Next: Output Variables, Prev: Output Streams, Up: Read and Print + +23.5 Output Functions +===================== + +This section describes the Lisp functions for printing Lisp objects. + + Some of the XEmacs printing functions add quoting characters to the +output when necessary so that it can be read properly. The quoting +characters used are `"' and `\'; they distinguish strings from symbols, +and prevent punctuation characters in strings and symbols from being +taken as delimiters when reading. *Note Printed Representation::, for +full details. You specify quoting or no quoting by the choice of +printing function. + + If the text is to be read back into Lisp, then it is best to print +with quoting characters to avoid ambiguity. Likewise, if the purpose is +to describe a Lisp object clearly for a Lisp programmer. However, if +the purpose of the output is to look nice for humans, then it is better +to print without quoting. + + Printing a self-referent Lisp object requires an infinite amount of +text. In certain cases, trying to produce this text leads to a stack +overflow. XEmacs detects such recursion and prints `#LEVEL' instead of +recursively printing an object already being printed. For example, +here `#0' indicates a recursive reference to the object at level 0 of +the current print operation: + + (setq foo (list nil)) + => (nil) + (setcar foo foo) + => (#0) + + In the functions below, STREAM stands for an output stream. (See +the previous section for a description of output streams.) If STREAM +is `nil' or omitted, it defaults to the value of `standard-output'. + + -- Function: print object &optional stream + The `print' function is a convenient way of printing. It outputs + the printed representation of OBJECT to STREAM, printing in + addition one newline before OBJECT and another after it. Quoting + characters are used. `print' returns OBJECT. For example: + + (progn (print 'The\ cat\ in) + (print "the hat") + (print " came back")) + -| + -| The\ cat\ in + -| + -| "the hat" + -| + -| " came back" + -| + => " came back" + + -- Function: prin1 object &optional stream + This function outputs the printed representation of OBJECT to + STREAM. It does not print newlines to separate output as `print' + does, but it does use quoting characters just like `print'. It + returns OBJECT. + + (progn (prin1 'The\ cat\ in) + (prin1 "the hat") + (prin1 " came back")) + -| The\ cat\ in"the hat"" came back" + => " came back" + + -- Function: princ object &optional stream + This function outputs the printed representation of OBJECT to + STREAM. It returns OBJECT. + + This function is intended to produce output that is readable by + people, not by `read', so it doesn't insert quoting characters and + doesn't put double-quotes around the contents of strings. It does + not add any spacing between calls. + + (progn + (princ 'The\ cat) + (princ " in the \"hat\"")) + -| The cat in the "hat" + => " in the \"hat\"" + + -- Function: terpri &optional stream + This function outputs a newline to STREAM. The name stands for + "terminate print". + + -- Function: write-char character &optional stream + This function outputs CHARACTER to STREAM. It returns CHARACTER. + + -- Function: prin1-to-string object &optional noescape + This function returns a string containing the text that `prin1' + would have printed for the same argument. + + (prin1-to-string 'foo) + => "foo" + (prin1-to-string (mark-marker)) + => "#" + + If NOESCAPE is non-`nil', that inhibits use of quoting characters + in the output. (This argument is supported in Emacs versions 19 + and later.) + + (prin1-to-string "foo") + => "\"foo\"" + (prin1-to-string "foo" t) + => "foo" + + See `format', in *Note String Conversion::, for other ways to + obtain the printed representation of a Lisp object as a string. + + +File: lispref.info, Node: Output Variables, Prev: Output Functions, Up: Read and Print + +23.6 Variables Affecting Output +=============================== + + -- Variable: standard-output + The value of this variable is the default output stream--the stream + that print functions use when the STREAM argument is `nil'. + + -- Variable: print-escape-newlines + If this variable is non-`nil', then newline characters in strings + are printed as `\n' and formfeeds are printed as `\f'. Normally + these characters are printed as actual newlines and formfeeds. + + This variable affects the print functions `prin1' and `print', as + well as everything that uses them. It does not affect `princ'. + Here is an example using `prin1': + + (prin1 "a\nb") + -| "a + -| b" + => "a + b" + + (let ((print-escape-newlines t)) + (prin1 "a\nb")) + -| "a\nb" + => "a + b" + + In the second expression, the local binding of + `print-escape-newlines' is in effect during the call to `prin1', + but not during the printing of the result. + + -- Variable: print-readably + If non-`nil', then all objects will be printed in a readable form. + If an object has no readable representation, then an error is + signalled. When `print-readably' is true, compiled-function + objects will be written in `#[...]' form instead of in + `#' form, and two-element lists of the + form `(quote object)' will be written as the equivalent `'object'. + Do not _set_ this variable; bind it instead. + + -- Variable: print-length + The value of this variable is the maximum number of elements of a + list that will be printed. If a list being printed has more than + this many elements, it is abbreviated with an ellipsis. + + If the value is `nil' (the default), then there is no limit. + + (setq print-length 2) + => 2 + (print '(1 2 3 4 5)) + -| (1 2 ...) + => (1 2 ...) + + -- Variable: print-level + The value of this variable is the maximum depth of nesting of + parentheses and brackets when printed. Any list or vector at a + depth exceeding this limit is abbreviated with an ellipsis. A + value of `nil' (which is the default) means no limit. + + This variable exists in version 19 and later versions. + + -- Variable: print-string-length + The value of this variable is the maximum number of characters of + a string that will be printed. If a string being printed has more + than this many characters, it is abbreviated with an ellipsis. + + -- Variable: print-gensym + If non-`nil', then uninterned symbols will be printed specially. + Uninterned symbols are those which are not present in `obarray', + that is, those which were made with `make-symbol' or by calling + `intern' with a second argument. + + When `print-gensym' is true, such symbols will be preceded by + `#:', which causes the reader to create a new symbol instead of + interning and returning an existing one. Beware: The `#:' syntax + creates a new symbol each time it is seen, so if you print an + object which contains two pointers to the same uninterned symbol, + `read' will not duplicate that structure. + + Also, since XEmacs has no real notion of packages, there is no way + for the printer to distinguish between symbols interned in no + obarray, and symbols interned in an alternate obarray. + + -- Variable: float-output-format + This variable holds the format descriptor string that Lisp uses to + print floats. This is a `%'-spec like those accepted by `printf' + in C, but with some restrictions. It must start with the two + characters `%.'. After that comes an integer precision + specification, and then a letter which controls the format. The + letters allowed are `e', `f' and `g'. + + * Use `e' for exponential notation `DIG.DIGITSeEXPT'. + + * Use `f' for decimal point notation `DIGITS.DIGITS'. + + * Use `g' to choose the shorter of those two formats for the + number at hand. + + The precision in any of these cases is the number of digits + following the decimal point. With `f', a precision of 0 means to + omit the decimal point. 0 is not allowed with `f' or `g'. + + A value of `nil' means to use `%.16g'. + + Regardless of the value of `float-output-format', a floating point + number will never be printed in such a way that it is ambiguous + with an integer; that is, a floating-point number will always be + printed with a decimal point and/or an exponent, even if the + digits following the decimal point are all zero. This is to + preserve read-equivalence. + + +File: lispref.info, Node: Minibuffers, Next: Command Loop, Prev: Read and Print, Up: Top + +24 Minibuffers +************** + +A "minibuffer" is a special buffer that XEmacs commands use to read +arguments more complicated than the single numeric prefix argument. +These arguments include file names, buffer names, and command names (as +in `M-x'). The minibuffer is displayed on the bottom line of the +frame, in the same place as the echo area, but only while it is in use +for reading an argument. + +* Menu: + +* Intro to Minibuffers:: Basic information about minibuffers. +* Text from Minibuffer:: How to read a straight text string. +* Object from Minibuffer:: How to read a Lisp object or expression. +* Minibuffer History:: Recording previous minibuffer inputs + so the user can reuse them. +* Completion:: How to invoke and customize completion. +* Yes-or-No Queries:: Asking a question with a simple answer. +* Multiple Queries:: Asking a series of similar questions. +* Reading a Password:: Reading a password from the terminal. +* Minibuffer Misc:: Various customization hooks and variables. + + +File: lispref.info, Node: Intro to Minibuffers, Next: Text from Minibuffer, Up: Minibuffers + +24.1 Introduction to Minibuffers +================================ + +In most ways, a minibuffer is a normal XEmacs buffer. Most operations +_within_ a buffer, such as editing commands, work normally in a +minibuffer. However, many operations for managing buffers do not apply +to minibuffers. The name of a minibuffer always has the form +` *Minibuf-NUMBER', and it cannot be changed. Minibuffers are +displayed only in special windows used only for minibuffers; these +windows always appear at the bottom of a frame. (Sometimes frames have +no minibuffer window, and sometimes a special kind of frame contains +nothing but a minibuffer window; see *Note Minibuffers and Frames::.) + + The minibuffer's window is normally a single line. You can resize it +temporarily with the window sizing commands; it reverts to its normal +size when the minibuffer is exited. You can resize it permanently by +using the window sizing commands in the frame's other window, when the +minibuffer is not active. If the frame contains just a minibuffer, you +can change the minibuffer's size by changing the frame's size. + + If a command uses a minibuffer while there is an active minibuffer, +this is called a "recursive minibuffer". The first minibuffer is named +` *Minibuf-0*'. Recursive minibuffers are named by incrementing the +number at the end of the name. (The names begin with a space so that +they won't show up in normal buffer lists.) Of several recursive +minibuffers, the innermost (or most recently entered) is the active +minibuffer. We usually call this "the" minibuffer. You can permit or +forbid recursive minibuffers by setting the variable +`enable-recursive-minibuffers'. + + Like other buffers, a minibuffer may use any of several local keymaps +(*note Keymaps::); these contain various exit commands and in some cases +completion commands (*note Completion::). + + * `minibuffer-local-map' is for ordinary input (no completion). + + * `minibuffer-local-completion-map' is for permissive completion. + + * `minibuffer-local-must-match-map' is for strict completion and for + cautious completion. + + +File: lispref.info, Node: Text from Minibuffer, Next: Object from Minibuffer, Prev: Intro to Minibuffers, Up: Minibuffers + +24.2 Reading Text Strings with the Minibuffer +============================================= + +Most often, the minibuffer is used to read text as a string. It can +also be used to read a Lisp object in textual form. The most basic +primitive for minibuffer input is `read-from-minibuffer'; it can do +either one. + + In most cases, you should not call minibuffer input functions in the +middle of a Lisp function. Instead, do all minibuffer input as part of +reading the arguments for a command, in the `interactive' spec. *Note +Defining Commands::. + + -- Function: read-from-minibuffer prompt-string &optional + initial-contents keymap read hist abbrev-table default + This function is the most general way to get input through the + minibuffer. By default, it accepts arbitrary text and returns it + as a string; however, if READ is non-`nil', then it uses `read' to + convert the text into a Lisp object (*note Input Functions::). + + The first thing this function does is to activate a minibuffer and + display it with PROMPT-STRING as the prompt. This value must be a + string. + + Then, if INITIAL-CONTENTS is a string, `read-from-minibuffer' + inserts it into the minibuffer, leaving point at the end. The + minibuffer appears with this text as its contents. + + The value of INITIAL-CONTENTS may also be a cons cell of the form + `(STRING . POSITION)'. This means to insert STRING in the + minibuffer but put point POSITION characters from the beginning, + rather than at the end. + + When the user types a command to exit the minibuffer, + `read-from-minibuffer' constructs the return value from the text in + the minibuffer. Normally it returns a string containing that text. + However, if READ is non-`nil', `read-from-minibuffer' reads the + text and returns the resulting Lisp object, unevaluated. (*Note + Input Functions::, for information about reading.) + + The argument DEFAULT specifies a default value to make available + through the history commands. It should be a string, or `nil'. + + If KEYMAP is non-`nil', that keymap is the local keymap to use in + the minibuffer. If KEYMAP is omitted or `nil', the value of + `minibuffer-local-map' is used as the keymap. Specifying a keymap + is the most important way to customize the minibuffer for various + applications such as completion. + + The argument ABBREV-TABLE specifies `local-abbrev-table' in the + minibuffer (*note Standard Abbrev Tables::). + + The argument HIST specifies which history list variable to use for + saving the input and for history commands used in the minibuffer. + It defaults to `minibuffer-history'. *Note Minibuffer History::. + + When the user types a command to exit the minibuffer, + `read-from-minibuffer' uses the text in the minibuffer to produce + its return value. Normally it simply makes a string containing + that text. However, if READ is non-`nil', `read-from-minibuffer' + reads the text and returns the resulting Lisp object, unevaluated. + (*Note Input Functions::, for information about reading.) + + *Usage note:* The INITIAL-CONTENTS argument and the DEFAULT + argument are two alternative features for more or less the same + job. It does not make sense to use both features in a single call + to `read-from-minibuffer'. In general, we recommend using + DEFAULT, since this permits the user to insert the default value + when it is wanted, but does not burden the user with deleting it + from the minibuffer on other occasions. However, if user is + supposed to edit default value, INITIAL-CONTENTS may be preferred. + + -- Function: read-string prompt &optional initial history default-value + This function reads a string from the minibuffer and returns it. + The arguments PROMPT and INITIAL are used as in + `read-from-minibuffer'. The keymap used is `minibuffer-local-map'. + + The optional argument HISTORY, if non-`nil', specifies a history + list and optionally the initial position in the list. The optional + argument DEFAULT-VALUE specifies a default value to return if the + user enters null input; it should be a string. + + This function is a simplified interface to the + `read-from-minibuffer' function: + + (read-string PROMPT INITIAL HISTORY DEFAULT) + == + (read-from-minibuffer PROMPT INITIAL nil nil + HISTORY nil DEFAULT))) + + -- Variable: minibuffer-local-map + This is the default local keymap for reading from the minibuffer. + By default, it makes the following bindings: + + `C-j' + `exit-minibuffer' + + + `exit-minibuffer' + + `C-g' + `abort-recursive-edit' + + `M-n' + `next-history-element' + + `M-p' + `previous-history-element' + + `M-r' + `next-matching-history-element' + + `M-s' + `previous-matching-history-element' + + +File: lispref.info, Node: Object from Minibuffer, Next: Minibuffer History, Prev: Text from Minibuffer, Up: Minibuffers + +24.3 Reading Lisp Objects with the Minibuffer +============================================= + +This section describes functions for reading Lisp objects with the +minibuffer. + + -- Function: read-expression prompt &optional initial history + default-value + This function reads a Lisp object using the minibuffer, and + returns it without evaluating it. The arguments PROMPT and + INITIAL are used as in `read-from-minibuffer'. + + The optional argument HISTORY, if non-`nil', specifies a history + list and optionally the initial position in the list. The optional + argument DEFAULT-VALUE specifies a default value to return if the + user enters null input; it should be a string. + + This is a simplified interface to the `read-from-minibuffer' + function: + + (read-expression PROMPT INITIAL HISTORY DEFAULT-VALUE) + == + (read-from-minibuffer PROMPT INITIAL nil t + HISTORY nil DEFAULT-VALUE) + + Here is an example in which we supply the string `"(testing)"' as + initial input: + + (read-expression + "Enter an expression: " (format "%s" '(testing))) + + ;; Here is how the minibuffer is displayed: + + ---------- Buffer: Minibuffer ---------- + Enter an expression: (testing)-!- + ---------- Buffer: Minibuffer ---------- + + The user can type immediately to use the initial input as a + default, or can edit the input. + + -- Function: read-minibuffer prompt &optional initial history + default-value + This is a FSF Emacs compatible function. Use `read-expression' + instead. + + -- Function: eval-minibuffer prompt &optional initial history + default-value + This function reads a Lisp expression using the minibuffer, + evaluates it, then returns the result. The arguments PROMPT and + INITIAL are used as in `read-from-minibuffer'. + + The optional argument HISTORY, if non-`nil', specifies a history + list and optionally the initial position in the list. The optional + argument DEFAULT-VALUE specifies a default value to return if the + user enters null input; it should be a string. + + This function simply evaluates the result of a call to + `read-expression': + + (eval-minibuffer PROMPT INITIAL) + == + (eval (read-expression PROMPT INITIAL)) + + -- Function: edit-and-eval-command prompt form &optional history + This function reads a Lisp expression in the minibuffer, and then + evaluates it. The difference between this command and + `eval-minibuffer' is that here the initial FORM is not optional + and it is treated as a Lisp object to be converted to printed + representation rather than as a string of text. It is printed with + `prin1', so if it is a string, double-quote characters (`"') + appear in the initial text. *Note Output Functions::. + + The first thing `edit-and-eval-command' does is to activate the + minibuffer with PROMPT as the prompt. Then it inserts the printed + representation of FORM in the minibuffer, and lets the user edit + it. When the user exits the minibuffer, the edited text is read + with `read' and then evaluated. The resulting value becomes the + value of `edit-and-eval-command'. + + In the following example, we offer the user an expression with + initial text which is a valid form already: + + (edit-and-eval-command "Please edit: " '(forward-word 1)) + + ;; After evaluation of the preceding expression, + ;; the following appears in the minibuffer: + + ---------- Buffer: Minibuffer ---------- + Please edit: (forward-word 1)-!- + ---------- Buffer: Minibuffer ---------- + + Typing right away would exit the minibuffer and evaluate the + expression, thus moving point forward one word. + `edit-and-eval-command' returns `t' in this example. + + +File: lispref.info, Node: Minibuffer History, Next: Completion, Prev: Object from Minibuffer, Up: Minibuffers + +24.4 Minibuffer History +======================= + +A "minibuffer history list" records previous minibuffer inputs so the +user can reuse them conveniently. A history list is actually a symbol, +not a list; it is a variable whose value is a list of strings (previous +inputs), most recent first. + + There are many separate history lists, used for different kinds of +inputs. It's the Lisp programmer's job to specify the right history +list for each use of the minibuffer. + + The basic minibuffer input functions `read-from-minibuffer' and +`completing-read' both accept an optional argument named HIST which is +how you specify the history list. Here are the possible values: + +VARIABLE + Use VARIABLE (a symbol) as the history list. + +(VARIABLE . STARTPOS) + Use VARIABLE (a symbol) as the history list, and assume that the + initial history position is STARTPOS (an integer, counting from + zero which specifies the most recent element of the history). + + If you specify STARTPOS, then you should also specify that element + of the history as the initial minibuffer contents, for consistency. + + If you don't specify HIST, then the default history list +`minibuffer-history' is used. For other standard history lists, see +below. You can also create your own history list variable; just +initialize it to `nil' before the first use. + + Both `read-from-minibuffer' and `completing-read' add new elements +to the history list automatically, and provide commands to allow the +user to reuse items on the list. The only thing your program needs to +do to use a history list is to initialize it and to pass its name to +the input functions when you wish. But it is safe to modify the list +by hand when the minibuffer input functions are not using it. + + Here are some of the standard minibuffer history list variables: + + -- Variable: minibuffer-history + The default history list for minibuffer history input. + + -- Variable: query-replace-history + A history list for arguments to `query-replace' (and similar + arguments to other commands). + + -- Variable: file-name-history + A history list for file name arguments. + + -- Variable: regexp-history + A history list for regular expression arguments. + + -- Variable: extended-command-history + A history list for arguments that are names of extended commands. + + -- Variable: shell-command-history + A history list for arguments that are shell commands. + + -- Variable: read-expression-history + A history list for arguments that are Lisp expressions to evaluate. + + -- Variable: Info-minibuffer-history + A history list for Info mode's minibuffer. + + -- Variable: Manual-page-minibuffer-history + A history list for `manual-entry'. + + There are many other minibuffer history lists, defined by various +libraries. An `M-x apropos' search for `history' should prove fruitful +in discovering them. + + +File: lispref.info, Node: Completion, Next: Yes-or-No Queries, Prev: Minibuffer History, Up: Minibuffers + +24.5 Completion +=============== + +"Completion" is a feature that fills in the rest of a name starting +from an abbreviation for it. Completion works by comparing the user's +input against a list of valid names and determining how much of the +name is determined uniquely by what the user has typed. For example, +when you type `C-x b' (`switch-to-buffer') and then type the first few +letters of the name of the buffer to which you wish to switch, and then +type (`minibuffer-complete'), Emacs extends the name as far as it +can. + + Standard XEmacs commands offer completion for names of symbols, +files, buffers, and processes; with the functions in this section, you +can implement completion for other kinds of names. + + The `try-completion' function is the basic primitive for completion: +it returns the longest determined completion of a given initial string, +with a given set of strings to match against. + + The function `completing-read' provides a higher-level interface for +completion. A call to `completing-read' specifies how to determine the +list of valid names. The function then activates the minibuffer with a +local keymap that binds a few keys to commands useful for completion. +Other functions provide convenient simple interfaces for reading +certain kinds of names with completion. + +* Menu: + +* Basic Completion:: Low-level functions for completing strings. + (These are too low level to use the minibuffer.) +* Minibuffer Completion:: Invoking the minibuffer with completion. +* Completion Commands:: Minibuffer commands that do completion. +* High-Level Completion:: Convenient special cases of completion + (reading buffer name, file name, etc.) +* Reading File Names:: Using completion to read file names. +* Programmed Completion:: Finding the completions for a given file name. + + +File: lispref.info, Node: Basic Completion, Next: Minibuffer Completion, Up: Completion + +24.5.1 Basic Completion Functions +--------------------------------- + +The two functions `try-completion' and `all-completions' have nothing +in themselves to do with minibuffers. We describe them in this chapter +so as to keep them near the higher-level completion features that do +use the minibuffer. + + -- Function: try-completion string collection &optional predicate + This function returns the longest common prefix of all possible + completions of STRING in COLLECTION. The value of COLLECTION must + be an alist, an obarray, or a function that implements a virtual + set of strings (see below). + + Completion compares STRING against each of the permissible + completions specified by COLLECTION; if the beginning of the + permissible completion equals STRING, it matches. If no + permissible completions match, `try-completion' returns `nil'. If + only one permissible completion matches, and the match is exact, + then `try-completion' returns `t'. Otherwise, the value is the + longest initial sequence common to all the permissible completions + that match. + + If COLLECTION is an alist (*note Association Lists::), the CARs of + the alist elements form the set of permissible completions. + + If COLLECTION is an obarray (*note Creating Symbols::), the names + of all symbols in the obarray form the set of permissible + completions. The global variable `obarray' holds an obarray + containing the names of all interned Lisp symbols. + + Note that the only valid way to make a new obarray is to create it + empty and then add symbols to it one by one using `intern'. Also, + you cannot intern a given symbol in more than one obarray. + + If the argument PREDICATE is non-`nil', then it must be a function + of one argument. It is used to test each possible match, and the + match is accepted only if PREDICATE returns non-`nil'. The + argument given to PREDICATE is either a cons cell from the alist + (the CAR of which is a string) or else it is a symbol (_not_ a + symbol name) from the obarray. + + You can also use a symbol that is a function as COLLECTION. Then + the function is solely responsible for performing completion; + `try-completion' returns whatever this function returns. The + function is called with three arguments: STRING, PREDICATE and + `nil'. (The reason for the third argument is so that the same + function can be used in `all-completions' and do the appropriate + thing in either case.) *Note Programmed Completion::. + + In the first of the following examples, the string `foo' is + matched by three of the alist CARs. All of the matches begin with + the characters `fooba', so that is the result. In the second + example, there is only one possible match, and it is exact, so the + value is `t'. + + (try-completion + "foo" + '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))) + => "fooba" + + (try-completion "foo" '(("barfoo" 2) ("foo" 3))) + => t + + In the following example, numerous symbols begin with the + characters `forw', and all of them begin with the word `forward'. + In most of the symbols, this is followed with a `-', but not in + all, so no more than `forward' can be completed. + + (try-completion "forw" obarray) + => "forward" + + Finally, in the following example, only two of the three possible + matches pass the predicate `test' (the string `foobaz' is too + short). Both of those begin with the string `foobar'. + + (defun test (s) + (> (length (car s)) 6)) + => test + (try-completion + "foo" + '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4)) + 'test) + => "foobar" + + -- Function: all-completions string collection &optional predicate + This function returns a list of all possible completions of STRING. + The arguments to this function are the same as those of + `try-completion'. + + If COLLECTION is a function, it is called with three arguments: + STRING, PREDICATE and `t'; then `all-completions' returns whatever + the function returns. *Note Programmed Completion::. + + Here is an example, using the function `test' shown in the example + for `try-completion': + + (defun test (s) + (> (length (car s)) 6)) + => test + + (all-completions + "foo" + '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4)) + 'test) + => ("foobar1" "foobar2") + + -- Variable: completion-ignore-case + If the value of this variable is non-`nil', XEmacs does not + consider case significant in completion. + + +File: lispref.info, Node: Minibuffer Completion, Next: Completion Commands, Prev: Basic Completion, Up: Completion + +24.5.2 Completion and the Minibuffer +------------------------------------ + +This section describes the basic interface for reading from the +minibuffer with completion. + + -- Function: completing-read prompt collection &optional predicate + require-match initial hist default + This function reads a string in the minibuffer, assisting the user + by providing completion. It activates the minibuffer with prompt + PROMPT, which must be a string. If INITIAL is non-`nil', + `completing-read' inserts it into the minibuffer as part of the + input. Then it allows the user to edit the input, providing + several commands to attempt completion. + + The actual completion is done by passing COLLECTION and PREDICATE + to the function `try-completion'. This happens in certain + commands bound in the local keymaps used for completion. + + If REQUIRE-MATCH is `t', the usual minibuffer exit commands won't + exit unless the input completes to an element of COLLECTION. If + REQUIRE-MATCH is neither `nil' nor `t', then the exit commands + won't exit unless the input typed is itself an element of + COLLECTION. If REQUIRE-MATCH is `nil', the exit commands work + regardless of the input in the minibuffer. + + However, empty input is always permitted, regardless of the value + of REQUIRE-MATCH; in that case, `completing-read' returns DEFAULT. + The value of DEFAULT (if non-`nil') is also available to the user + through the history commands. + + The user can exit with null input by typing with an empty + minibuffer. Then `completing-read' returns `""'. This is how the + user requests whatever default the command uses for the value being + read. The user can return using in this way regardless of + the value of REQUIRE-MATCH, and regardless of whether the empty + string is included in COLLECTION. + + The function `completing-read' works by calling `read-expression'. + It uses `minibuffer-local-completion-map' as the keymap if + REQUIRE-MATCH is `nil', and uses `minibuffer-local-must-match-map' + if REQUIRE-MATCH is non-`nil'. *Note Completion Commands::. + + The argument HIST specifies which history list variable to use for + saving the input and for minibuffer history commands. It defaults + to `minibuffer-history'. *Note Minibuffer History::. + + Completion ignores case when comparing the input against the + possible matches, if the built-in variable + `completion-ignore-case' is non-`nil'. *Note Basic Completion::. + + Here's an example of using `completing-read': + + (completing-read + "Complete a foo: " + '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4)) + nil t "fo") + + ;; After evaluation of the preceding expression, + ;; the following appears in the minibuffer: + + ---------- Buffer: Minibuffer ---------- + Complete a foo: fo-!- + ---------- Buffer: Minibuffer ---------- + + If the user then types ` b ', `completing-read' + returns `barfoo'. + + The `completing-read' function binds three variables to pass + information to the commands that actually do completion. These + variables are `minibuffer-completion-table', + `minibuffer-completion-predicate' and + `minibuffer-completion-confirm'. For more information about them, + see *Note Completion Commands::. + + +File: lispref.info, Node: Completion Commands, Next: High-Level Completion, Prev: Minibuffer Completion, Up: Completion + +24.5.3 Minibuffer Commands That Do Completion +--------------------------------------------- + +This section describes the keymaps, commands and user options used in +the minibuffer to do completion. + + -- Variable: minibuffer-local-completion-map + `completing-read' uses this value as the local keymap when an + exact match of one of the completions is not required. By + default, this keymap makes the following bindings: + + `?' + `minibuffer-completion-help' + + + `minibuffer-complete-word' + + + `minibuffer-complete' + + with other characters bound as in `minibuffer-local-map' (*note + Text from Minibuffer::). + + -- Variable: minibuffer-local-must-match-map + `completing-read' uses this value as the local keymap when an + exact match of one of the completions is required. Therefore, no + keys are bound to `exit-minibuffer', the command that exits the + minibuffer unconditionally. By default, this keymap makes the + following bindings: + + `?' + `minibuffer-completion-help' + + + `minibuffer-complete-word' + + + `minibuffer-complete' + + `C-j' + `minibuffer-complete-and-exit' + + + `minibuffer-complete-and-exit' + + with other characters bound as in `minibuffer-local-map'. + + -- Variable: minibuffer-completion-table + The value of this variable is the alist or obarray used for + completion in the minibuffer. This is the global variable that + contains what `completing-read' passes to `try-completion'. It is + used by minibuffer completion commands such as + `minibuffer-complete-word'. + + -- Variable: minibuffer-completion-predicate + This variable's value is the predicate that `completing-read' + passes to `try-completion'. The variable is also used by the other + minibuffer completion functions. + + -- Command: minibuffer-complete-word + This function completes the minibuffer contents by at most a single + word. Even if the minibuffer contents have only one completion, + `minibuffer-complete-word' does not add any characters beyond the + first character that is not a word constituent. *Note Syntax + Tables::. + + -- Command: minibuffer-complete + This function completes the minibuffer contents as far as possible. + + -- Command: minibuffer-complete-and-exit + This function completes the minibuffer contents, and exits if + confirmation is not required, i.e., if + `minibuffer-completion-confirm' is `nil'. If confirmation _is_ + required, it is given by repeating this command immediately--the + command is programmed to work without confirmation when run twice + in succession. + + -- Variable: minibuffer-completion-confirm + When the value of this variable is non-`nil', XEmacs asks for + confirmation of a completion before exiting the minibuffer. The + function `minibuffer-complete-and-exit' checks the value of this + variable before it exits. + + -- Command: minibuffer-completion-help + This function creates a list of the possible completions of the + current minibuffer contents. It works by calling `all-completions' + using the value of the variable `minibuffer-completion-table' as + the COLLECTION argument, and the value of + `minibuffer-completion-predicate' as the PREDICATE argument. The + list of completions is displayed as text in a buffer named + `*Completions*'. + + -- Function: display-completion-list completions &rest cl-keys + This function displays COMPLETIONS to the stream in + `standard-output', usually a buffer. (*Note Read and Print::, for + more information about streams.) The argument COMPLETIONS is + normally a list of completions just returned by `all-completions', + but it does not have to be. Each element may be a symbol or a + string, either of which is simply printed, or a list of two + strings, which is printed as if the strings were concatenated. + + This function is called by `minibuffer-completion-help'. The most + common way to use it is together with + `with-output-to-temp-buffer', like this: + + (with-output-to-temp-buffer "*Completions*" + (display-completion-list + (all-completions (buffer-string) my-alist))) + + -- User Option: completion-auto-help + If this variable is non-`nil', the completion commands + automatically display a list of possible completions whenever + nothing can be completed because the next character is not + uniquely determined. + + +File: lispref.info, Node: High-Level Completion, Next: Reading File Names, Prev: Completion Commands, Up: Completion + +24.5.4 High-Level Completion Functions +--------------------------------------- + +This section describes the higher-level convenient functions for +reading certain sorts of names with completion. + + In most cases, you should not call these functions in the middle of a +Lisp function. When possible, do all minibuffer input as part of +reading the arguments for a command, in the `interactive' spec. *Note +Defining Commands::. + + -- Function: read-buffer prompt &optional default existing + This function reads the name of a buffer and returns it as a + string. The argument DEFAULT is the default name to use, the + value to return if the user exits with an empty minibuffer. If + non-`nil', it should be a string or a buffer. It is mentioned in + the prompt, but is not inserted in the minibuffer as initial input. + + If EXISTING is non-`nil', then the name specified must be that of + an existing buffer. The usual commands to exit the minibuffer do + not exit if the text is not valid, and does completion to + attempt to find a valid name. (However, DEFAULT is not checked + for validity; it is returned, whatever it is, if the user exits + with the minibuffer empty.) + + In the following example, the user enters `minibuffer.t', and then + types . The argument EXISTING is `t', and the only buffer + name starting with the given input is `minibuffer.texi', so that + name is the value. + + (read-buffer "Buffer name? " "foo" t) + ;; After evaluation of the preceding expression, + ;; the following prompt appears, + ;; with an empty minibuffer: + + ---------- Buffer: Minibuffer ---------- + Buffer name? (default foo) -!- + ---------- Buffer: Minibuffer ---------- + + ;; The user types `minibuffer.t '. + => "minibuffer.texi" + + -- Function: read-command prompt &optional default-value + This function reads the name of a command and returns it as a Lisp + symbol. The argument PROMPT is used as in `read-from-minibuffer'. + Recall that a command is anything for which `commandp' returns + `t', and a command name is a symbol for which `commandp' returns + `t'. *Note Interactive Call::. + + The argument DEFAULT-VALUE specifies what to return if the user + enters null input. It can be a symbol or a string; if it is a + string, `read-command' interns it before returning it. If DEFAULT + is `nil', that means no default has been specified; then if the + user enters null input, the return value is `nil'. + + (read-command "Command name? ") + + ;; After evaluation of the preceding expression, + ;; the following prompt appears with an empty minibuffer: + + ---------- Buffer: Minibuffer ---------- + Command name? + ---------- Buffer: Minibuffer ---------- + + If the user types `forward-c ', then this function returns + `forward-char'. + + The `read-command' function is a simplified interface to the + function `completing-read'. It uses the variable `obarray' so as + to complete in the set of extant Lisp symbols, and it uses the + `commandp' predicate so as to accept only command names: + + (read-command PROMPT) + == + (intern (completing-read PROMPT obarray + 'commandp t nil)) + + -- Function: read-variable prompt &optional default-value + This function reads the name of a user variable and returns it as a + symbol. + + The argument DEFAULT-VALUE specifies what to return if the user + enters null input. It can be a symbol or a string; if it is a + string, `read-variable' interns it before returning it. If + DEFAULT-VALUE is `nil', that means no default has been specified; + then if the user enters null input, the return value is `nil'. + + (read-variable "Variable name? ") + + ;; After evaluation of the preceding expression, + ;; the following prompt appears, + ;; with an empty minibuffer: + + ---------- Buffer: Minibuffer ---------- + Variable name? -!- + ---------- Buffer: Minibuffer ---------- + + If the user then types `fill-p ', `read-variable' returns + `fill-prefix'. + + This function is similar to `read-command', but uses the predicate + `user-variable-p' instead of `commandp': + + (read-variable PROMPT) + == + (intern + (completing-read PROMPT obarray + 'user-variable-p t nil)) + + +File: lispref.info, Node: Reading File Names, Next: Programmed Completion, Prev: High-Level Completion, Up: Completion + +24.5.5 Reading File Names +------------------------- + +Here is another high-level completion function, designed for reading a +file name. It provides special features including automatic insertion +of the default directory. + + -- Function: read-file-name prompt &optional directory default + existing initial history + This function reads a file name in the minibuffer, prompting with + PROMPT and providing completion. If DEFAULT is non-`nil', then + the function returns DEFAULT if the user just types . + DEFAULT is not checked for validity; it is returned, whatever it + is, if the user exits with the minibuffer empty. + + If EXISTING is non-`nil', then the user must specify the name of + an existing file; performs completion to make the name valid + if possible, and then refuses to exit if it is not valid. If the + value of EXISTING is neither `nil' nor `t', then also + requires confirmation after completion. If EXISTING is `nil', + then the name of a nonexistent file is acceptable. + + The argument DIRECTORY specifies the directory to use for + completion of relative file names. If `insert-default-directory' + is non-`nil', DIRECTORY is also inserted in the minibuffer as + initial input. It defaults to the current buffer's value of + `default-directory'. + + If you specify INITIAL, that is an initial file name to insert in + the buffer (after DIRECTORY, if that is inserted). In this case, + point goes at the beginning of INITIAL. The default for INITIAL + is `nil'--don't insert any file name. To see what INITIAL does, + try the command `C-x C-v'. + + Here is an example: + + (read-file-name "The file is ") + + ;; After evaluation of the preceding expression, + ;; the following appears in the minibuffer: + + ---------- Buffer: Minibuffer ---------- + The file is /gp/gnu/elisp/-!- + ---------- Buffer: Minibuffer ---------- + + Typing `manual ' results in the following: + + ---------- Buffer: Minibuffer ---------- + The file is /gp/gnu/elisp/manual.texi-!- + ---------- Buffer: Minibuffer ---------- + + If the user t