From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED.blaine.gmane.org!not-for-mail From: Robert Pluim Newsgroups: gmane.emacs.devel Subject: Re: Native line numbers landed on master Date: Wed, 09 Oct 2019 09:19:57 +0200 Message-ID: References: <834l4xbfmp.fsf@gnu.org> <20191001225254.mwjnxlynjdc3mz7y@Ergus> <83lfu389vn.fsf@gnu.org> <87ftk9v4kx.fsf@wavexx.thregr.org> <83wodl54yt.fsf@gnu.org> <87pnjchm7p.fsf@wavexx.thregr.org> <83pnj8zff9.fsf@gnu.org> <83blurxw6a.fsf@gnu.org> Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Injection-Info: blaine.gmane.org; posting-host="blaine.gmane.org:195.159.176.226"; logging-data="42657"; mail-complaints-to="usenet@blaine.gmane.org" Cc: emacs-devel@gnu.org To: Eli Zaretskii Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Wed Oct 09 19:23:01 2019 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([209.51.188.17]) by blaine.gmane.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.89) (envelope-from ) id 1iIFfx-000Ayd-At for ged-emacs-devel@m.gmane.org; Wed, 09 Oct 2019 19:23:01 +0200 Original-Received: from localhost ([::1]:52986 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1iIFfv-00038D-Ve for ged-emacs-devel@m.gmane.org; Wed, 09 Oct 2019 13:23:00 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:39293) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1iI6GR-0008Qw-5Y for emacs-devel@gnu.org; Wed, 09 Oct 2019 03:20:04 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1iI6GP-0005qv-ME for emacs-devel@gnu.org; Wed, 09 Oct 2019 03:20:03 -0400 Original-Received: from mail-wm1-x335.google.com ([2a00:1450:4864:20::335]:51032) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1iI6GP-0005qe-DS; Wed, 09 Oct 2019 03:20:01 -0400 Original-Received: by mail-wm1-x335.google.com with SMTP id 5so1187492wmg.0; Wed, 09 Oct 2019 00:20:01 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=from:to:cc:subject:references:date:in-reply-to:message-id :mime-version:content-transfer-encoding; bh=z5ofod4Xk/0/6aKmwjW0+wIPYLw4rh0nWME83zAfd+0=; b=rZ9yvcB/EzWrSRwzc6c49PZx+7Iyyko+5VU1cOBQQF6Qg5oyaappIcm4zqAuSQZsRN 073JKcFvoTMRkgGDhN2+eP15GBcptfW9ny+i0+imEwtouxWWJktZ/rT7Q5vN3mi4YXH4 Q2j8HVTvx3UfgZg0U9qRhXXSnjOC1VxxyaYmtzHKkkqPtxVuBWFb9MH6HoxZPRZ3aZlg B4feTxz6UTDJKnEYLLC3gk0xtT34VWm3dnTfivVHaDs6vv1ivR7MZ7LAW1due/EFHb92 lqKDn7CZyrAYTU2BEVes9i5LACUPRXcmQwEgJ2OrcbtcrFNtdJheI2qZbOCfpkWLQVAq C0Tg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:references:date:in-reply-to :message-id:mime-version:content-transfer-encoding; bh=z5ofod4Xk/0/6aKmwjW0+wIPYLw4rh0nWME83zAfd+0=; b=T3o3i9fVc7co8/mzDzJaHKhSghC26I2/rLe3fubomxdRcgpKcfm3XVYTFHF7KM18zp /2YENlV7ml1520dZ1XpJr0rWPx9fJuKAB5Ue28enmiIFkzuN7ymO3WnXtXxwQazjWiyF x72EXQBcV3y64kG+kRkWS3egxlPD/ZB7HSgu5mvwnUB73RT2u8gjx5B+3MGAvVge690T w4JXe+AFENpKeFFb+xVZTou4bklRGren4oYuyiXVBXTDNNtDBjPzFa+Zykyuj8pbuB7w A8Ges7vz+f6B6JH8ly/v4Iy92H721USy5GK5oRR/6cGp15lnFlFfkpZ/qMweOSM5s6ev cRDw== X-Gm-Message-State: APjAAAXewSBcK9wSxXPalE0nDNm/whADj5VG2vMJEppPwZuaR2e04kz/ rXwwYhPWSLiJdXTtQBc78ay3V+/sAkU= X-Google-Smtp-Source: APXvYqyvPQOZAVK2BgpHA39dpaetwOvCZqg7AJ3OkPe/qErdwTZ1tACjpJcJ9m+JoIpzGWOg4RqEhQ== X-Received: by 2002:a05:600c:20ca:: with SMTP id y10mr1500059wmm.168.1570605599528; Wed, 09 Oct 2019 00:19:59 -0700 (PDT) Original-Received: from rpluim-mac ([149.5.228.1]) by smtp.gmail.com with ESMTPSA id o4sm2697469wre.91.2019.10.09.00.19.58 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 09 Oct 2019 00:19:58 -0700 (PDT) In-Reply-To: <83blurxw6a.fsf@gnu.org> (Eli Zaretskii's message of "Tue, 08 Oct 2019 15:23:57 +0300") X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 2a00:1450:4864:20::335 X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Original-Sender: "Emacs-devel" Xref: news.gmane.org gmane.emacs.devel:240770 Archived-At: >>>>> On Tue, 08 Oct 2019 15:23:57 +0300, Eli Zaretskii said: Eli> Instead of "Lisp-level" and "C-level", which IMO are somewhat uncl= ear, Eli> I'd use the likes of "the name of the variable to be used by Lisp Eli> programs" and "the name of the variable in the C source". Done >> +@item doc >> +The documentation for the variable, as a C comment. Eli> Here, please include a cross-reference to the tips about writing d= oc Eli> strings. Done >> + By convention, when defining variables of a ``native'' type >> +(@code{int} and @code{bool}), the name of the C variable is the same >> +as the name of the Lisp variable with ``-'' replaced by ``_''. When >> +the variable can hold any Lisp object, the convention is >> +to also prefix the C variable name with ``V''. i.e. Eli> I think -, _, and V should be in @code or @samp, not in quotes. A= lso, Eli> I'd mention explicitly that the C data type of the latter category= is Eli> Lisp_Object. Done >> +If you want to define a constant symbol rather than a variable, use >> +@code{DEFSYM} instead. e.g. >> + >> +@smallexample >> +DEFSYM ("Qmy_symbol", "my-symbol"); >> +@end smallexample Eli> This is IMO confusing, because it doesn't explain when would the C Eli> programmer want "to define a constant symbol rather than a variabl= e". Eli> I think it's important to explain that the symbol corresponding to= a Eli> variable is needed where in Lisp one would use a quoted symbol. A Eli> good example is the use of specbind which is the equivalent of Eli> let-binding on the Lisp level. Not just confusing, my example was wrong. I expanded that bit. Eli> Bonus points for adding information missing from the above, such as Eli> how to define buffer-local variables (see init_buffer_once), and h= ow Eli> to define custom forms for variables defined in C. You=CA=BCre a hard taskmaster Eli :-) . I=CA=BCve done my best, although I = don=CA=BCt see where init_buffer_once comes in. There=CA=BCs a sentence further down that talks about cus-start.el, I added a cross-reference to the defcustom node. * doc/lispref/internals.texi (Writing Emacs Primitives): Add description of DEFVAR_* arguments. Describe variable naming conventions. Explain 'specbind' and how to create buffer-local variables. diff --git a/doc/lispref/internals.texi b/doc/lispref/internals.texi index c52999e1cd..45725c3c80 100644 --- a/doc/lispref/internals.texi +++ b/doc/lispref/internals.texi @@ -945,7 +945,7 @@ Writing Emacs Primitives @anchor{Defining Lisp variables in C} @vindex byte-boolean-vars @cindex defining Lisp variables in C -@cindex @code{DEFVAR_INT}, @code{DEFVAR_LISP}, @code{DEFVAR_BOOL} +@cindex @code{DEFVAR_INT}, @code{DEFVAR_LISP}, @code{DEFVAR_BOOL}, @code{D= EFSYM} The function @code{syms_of_@var{filename}} is also the place to define any C variables that are to be visible as Lisp variables. @code{DEFVAR_LISP} makes a C variable of type @code{Lisp_Object} visible @@ -956,15 +956,71 @@ Writing Emacs Primitives defined with @code{DEFVAR_BOOL} are automatically added to the list @code{byte-boolean-vars} used by the byte compiler. =20 + These macros all expect three arguments: + +@table @code +@item lname +The name of the variable to be used by Lisp programs. +@item vname +The name of the variable in the C sources. +@item doc +The documentation for the variable, as a C +comment. @xref{Documentation Basics} for more details. +@end table + + By convention, when defining variables of a ``native'' type +(@code{int} and @code{bool}), the name of the C variable is the name +of the Lisp variable with @code{-} replaced by @code{_}. When the +variable has type @code{Lisp_Object}, the convention is to also prefix +the C variable name with ``V''. i.e. + +@smallexample +DEFVAR_INT ("my-int-variable", my_int_variable, + doc: /* An integer variable. */); + +DEFVAR_LISP ("my-lisp-variable", Vmy_lisp_variable, + doc: /* A Lisp variable. */); +@end smallexample + + There are situations in Lisp where you need to refer to the symbol +itself rather than the value of that symbol. One such case is when +temporarily overriding the value of a variable, which in Lisp is done +with @code{let}. In C sources, this is done by defining a +corresponding, constant symbol, and using @code{specbind}. By +convention @code{Qmy_lisp_variable} corresponds to +@code{Vmy_lisp_variable}; to define it, use the @code{DEFSYM} macro. +i.e. + +@smallexample +DEFSYM (Qmy_lisp_variable, "my-lisp-variable"); +@end smallexample + + To perform the actual binding: + +@smallexample +specbind (Qmy_lisp_variable, Qt); +@end smallexample + + Another use for constant symbols is when creating a buffer-local +variable (@pxref{Buffer-Local Variables}). In C this is done with +@code{Fmake_variable_buffer_local} in combination with @code{DEFSYM}, +i.e. + +@smallexample +DEFSYM (Qmy_lisp_variable, "my-lisp-variable"); +Fmake_variable_buffer_local (Qmy_lisp_variable); +@end smallexample + @cindex defining customization variables in C If you want to make a Lisp variable that is defined in C behave like one declared with @code{defcustom}, add an appropriate entry to -@file{cus-start.el}. +@file{cus-start.el}. @xref{Variable Definitions} for a description of +the format to use. =20 @cindex @code{staticpro}, protection from GC - If you define a file-scope C variable of type @code{Lisp_Object}, -you must protect it from garbage-collection by calling @code{staticpro} -in @code{syms_of_@var{filename}}, like this: + If you directly define a file-scope C variable of type +@code{Lisp_Object}, you must protect it from garbage-collection by +calling @code{staticpro} in @code{syms_of_@var{filename}}, like this: =20 @example staticpro (&@var{variable});