From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Yuan Fu Newsgroups: gmane.emacs.devel Subject: Re: Tree-sitter documentation Date: Tue, 8 Nov 2022 10:44:29 -0800 Message-ID: <2A694F4A-7CC6-4B28-A4E5-2B60DCBC1AB2@gmail.com> References: <48A65188-BBC6-442F-A552-5FEA1416F936@gmail.com> <83a653ynec.fsf@gnu.org> <14DDD315-2399-41F7-B1C6-10433C27CF5C@gmail.com> <83h6z9y0fa.fsf@gnu.org> Mime-Version: 1.0 (Mac OS X Mail 16.0 \(3696.120.41.1.1\)) Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="30974"; mail-complaints-to="usenet@ciao.gmane.io" Cc: emacs-devel@gnu.org To: Eli Zaretskii Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Tue Nov 08 19:45:33 2022 Return-path: Envelope-to: ged-emacs-devel@m.gmane-mx.org Original-Received: from lists.gnu.org ([209.51.188.17]) by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1osTbI-0007pn-Tb for ged-emacs-devel@m.gmane-mx.org; Tue, 08 Nov 2022 19:45:32 +0100 Original-Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1osTaU-00039i-Cl; Tue, 08 Nov 2022 13:44:42 -0500 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1osTaP-00039A-FI for emacs-devel@gnu.org; Tue, 08 Nov 2022 13:44:37 -0500 Original-Received: from mail-pl1-x632.google.com ([2607:f8b0:4864:20::632]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1osTaN-0001mu-R7; Tue, 08 Nov 2022 13:44:37 -0500 Original-Received: by mail-pl1-x632.google.com with SMTP id u6so14930198plq.12; Tue, 08 Nov 2022 10:44:35 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=to:references:message-id:content-transfer-encoding:cc:date :in-reply-to:from:subject:mime-version:from:to:cc:subject:date :message-id:reply-to; bh=4RK77N0mkB7zDdHA2uyazH/jndNv8SarUhW6XUemqqk=; b=Ma3MbkkytC4jeBOF0j4chU5buQWFjmODe2iQxV/s5s94IyKElHHnXD6WU/T+p2hGHI DjMwrc76QhywRTkzYb4zT9cDBKrl/0PAzFvOdK2Z3Bb/QpycDULs0zv/f2p/x+azkcPj 8fAi+ZtgTjw8ScHDQyPFizlxnDwWLCEdvp5Bht6YLOLmNzyoyyjImax1li4XgwoHtigk tQDvYY7zxv45vXt/eZEvTtF2mCu8UiLpd5nmgE3FEA2xkswzl/QajLNe92obAiOz2t0j gXRUrUynidOplRW94RQOSFf6YYrvGzCNg/n5PXPNhXw9Lofo8n/2z2sr9XQ4JPhXBdFu 7VOg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=to:references:message-id:content-transfer-encoding:cc:date :in-reply-to:from:subject:mime-version:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=4RK77N0mkB7zDdHA2uyazH/jndNv8SarUhW6XUemqqk=; b=isKmwvu+BAaeEw2Nw7rFzxdnf3IqIv92pfvTuIuhWdz92GtkYmxxalrbkTSvOp3YhL 3scziU9i7ZIhevCO64/9zkcIxYKQZ+WPz1JWabtrXL/vOWKJMjCmXurkd9RzLGjaVz5P IPBwjC6EaqTTQ/5h/CH6icZKUy7AnnTj1d5Atm6zvWiyABliVKdB2EnKmvqiHSN6jIIv m1uciR4JDfpSvxyqkt2+sJbxYHJoY3gHBuf7ru08HfBNGlmC+cubfnwXGHrimReHlhgA WQsMjRe4ZKxCa4iGYWVn3sxFrEQ9pY6YFpFfD5ePEici0WYSzyV7sUblTvppt2ED2l8Q DFNw== X-Gm-Message-State: ACrzQf3mKWf/sfgQ7et1voGxD8tDfYtlCYdweo3PLWsXFWnntJFiODtk bIvWzdhRYIqpHAdFZQ3WMl8RzdRVUkI= X-Google-Smtp-Source: AMsMyM7w9AzGK/sdfb5sToL5ahPZeNg47OLJhHBmHU0wQlmYBdHufBtcAE7zL9KXRyl9IjA7vCsFVA== X-Received: by 2002:a17:903:2446:b0:187:11c6:6a1b with SMTP id l6-20020a170903244600b0018711c66a1bmr50666442pls.39.1667933073508; Tue, 08 Nov 2022 10:44:33 -0800 (PST) Original-Received: from smtpclient.apple (cpe-172-117-161-177.socal.res.rr.com. [172.117.161.177]) by smtp.gmail.com with ESMTPSA id c16-20020a056a00009000b0056299fd2ba2sm6689942pfj.162.2022.11.08.10.44.31 (version=TLS1_2 cipher=ECDHE-ECDSA-AES128-GCM-SHA256 bits=128/128); Tue, 08 Nov 2022 10:44:32 -0800 (PST) In-Reply-To: <83h6z9y0fa.fsf@gnu.org> X-Mailer: Apple Mail (2.3696.120.41.1.1) Received-SPF: pass client-ip=2607:f8b0:4864:20::632; envelope-from=casouri@gmail.com; helo=mail-pl1-x632.google.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, FREEMAIL_FROM=0.001, RCVD_IN_DNSWL_NONE=-0.0001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.29 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-mx.org@gnu.org Original-Sender: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Xref: news.gmane.io gmane.emacs.devel:299358 Archived-At: > On Nov 8, 2022, at 6:40 AM, Eli Zaretskii wrote: >=20 >> From: Yuan Fu >> Date: Mon, 7 Nov 2022 12:47:30 -0800 >> Cc: emacs-devel@gnu.org >>=20 >>> In that case, "triplets" is definitely incorrect, but I had no way = of >>> understanding that this is possible. >>>=20 >>> It should be possible top describe this kind of argument list, but >>> does it really have to be so complicated? These are not internal >>> functions, so Lisp programmers will have to battle with this = signature >>> all the time. Can we make the function's signature easier to >>> document, understand, and use? >>>=20 >>> For example, what about accepting an alist as the argument, where = each >>> alist element specifies a query and its keyword/value pairs that >>> customize the query? >>=20 >> Alists has too much layers of parenthesizes that is verbose and easy = to get wrong. Compare: >=20 > I don't share your pessimism about alists. And the way the functions > are defined now are also very error-prone and complicate the code, > which needs to distinguish between several very different signatures. Ah, I=E2=80=99m not saying alist per se has too much layers of = parenthesizes, but if we use alists rather than keywords in = treesit-font-lock-rules, there really are a lot of parenthesizes. The = current signature might be harder to formally explain, but should be = pretty intuitive, it=E2=80=99s just a series of queries, and queries can = have keyword value pairs preceding it that adds meta information to the = query. I might help to think of treesit-font-lock-rules not as a function but = as a macro.=20 The code to handle this signature isn=E2=80=99t particularly = error-prone, the signal forms you see are just nice type-checks that I = added for developer=E2=80=99s aid. They check, for example, that the = value of a :language keyword is a symbol, the value of an :override = keyword is one of the five possible values, etc. These checks are not = related to the signature. >=20 > How about making the query itself the value of a keyword/value pair? > Like this: >=20 > :language 'python > :override t > :feature 'string > :query '((string :anchor "\"" @python--treesit-fontify-string) > (string) @contextual) It=E2=80=99s ok, but query isn=E2=80=99t the same as other things. Query = is the subject and other keywords adds information to it. I tried to = improve the documentation of treesit-font-lock-rules, so hopefully = changing the signature is not needed. Is the new version ok to you? Yuan=