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: Writing manuals Date: Fri, 3 Sep 2021 22:35:40 -0700 Message-ID: References: <83lf4x1kme.fsf@gnu.org> <83k0kh1j84.fsf@gnu.org> Mime-Version: 1.0 (Mac OS X Mail 14.0 \(3654.120.0.1.13\)) 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="13255"; 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 Sat Sep 04 07:36:30 2021 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 1mMOLt-0003DF-Qv for ged-emacs-devel@m.gmane-mx.org; Sat, 04 Sep 2021 07:36:29 +0200 Original-Received: from localhost ([::1]:45676 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1mMOLs-0008Nw-Bw for ged-emacs-devel@m.gmane-mx.org; Sat, 04 Sep 2021 01:36:28 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:49444) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1mMOLA-0006zX-BG for emacs-devel@gnu.org; Sat, 04 Sep 2021 01:35:47 -0400 Original-Received: from mail-qk1-x72e.google.com ([2607:f8b0:4864:20::72e]:33728) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1mMOL8-00088X-Ol; Sat, 04 Sep 2021 01:35:44 -0400 Original-Received: by mail-qk1-x72e.google.com with SMTP id b64so1344275qkg.0; Fri, 03 Sep 2021 22:35:42 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=mime-version:subject:from:in-reply-to:date:cc :content-transfer-encoding:message-id:references:to; bh=rKsLSPyCRaNeVzyBxd+kNmg1gapbr7Wl9mOMHb/2nOA=; b=fwF+bnWz7w3bPuSe1fapxEmFlQWVmckiDjSFar1HZeBE84ZiFdRANKuug4SoQkkzTp RG9+exDfjWr2Jva2gxOOZZl1e4xF/BGtFpSGy5lckDc1eRyYMbFZcFDZ+j8E2Pc2HSFh CaXWro3vlO3XD6uJPkZcl1nJ58Z+Zx3W0flKEkjBnCZFH+HXGoQPmOx4P/nPe34XdmMr woYVmzqNQnOXmkr3EQ3tn8t4fEnSTPVN6sHOMrFyOQEubiLz2jAht7wrlitI6vpkWmQF sBENU4aDiCAFK43/tillqvPYLZPweKU2PhVZO26gzQHUpYwFCrvEoz64aLOouSbFEIFe 08xA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:mime-version:subject:from:in-reply-to:date:cc :content-transfer-encoding:message-id:references:to; bh=rKsLSPyCRaNeVzyBxd+kNmg1gapbr7Wl9mOMHb/2nOA=; b=XDOM9Rpv8MPMM8Ui1hFEvoPl2+HqBRoamU8Az3ym63BA2x46+KjbZAb+Jde8Z7zZVB nq3vs93yYh0/GJCXqd6u3wXImxhIxWil/0vgijxtFbXC+MmzcA5H6rJpaQt2aDiOl6fO IR2v1Q2gzUXlcqmb0b0jERpgivTUb1paoBIsLjlvF9EVMYHUUjXuiTVJoMCCE0LAF4IJ w3ygvxnno1nZmOkRY122QBTxJAm5KJR0IbC5Ob0BDBQrNNnB/mql1B3RW3V/rn1X0AUf Ymf0fE7laUDifnQk7mliizJeqMwb2Pqqm/jHrCKRdUEMcNO2L4xqYnjBap+ZId4i0/ll epjg== X-Gm-Message-State: AOAM531RYW1Xde4Vwy7sjalpjhAIjgAXksCgULUVqghs90VDyeKK1LgB BMdsUXyfaLMeFVq5jo1/tjaAwCd/3FnPkQ== X-Google-Smtp-Source: ABdhPJx4zNyaHQNS2hbJ+F8s5O1QNW/Weh23PSZLvpxo67/J3+ralCIZ8gYfAlXuNC+unhbP5y/MMA== X-Received: by 2002:ae9:f50a:: with SMTP id o10mr1967360qkg.387.1630733741274; Fri, 03 Sep 2021 22:35:41 -0700 (PDT) Original-Received: from smtpclient.apple ([2600:1700:2ec7:8c9f:a86e:bc67:ca96:8c27]) by smtp.gmail.com with ESMTPSA id s16sm998389qtq.31.2021.09.03.22.35.40 (version=TLS1_2 cipher=ECDHE-ECDSA-AES128-GCM-SHA256 bits=128/128); Fri, 03 Sep 2021 22:35:40 -0700 (PDT) In-Reply-To: <83k0kh1j84.fsf@gnu.org> X-Mailer: Apple Mail (2.3654.120.0.1.13) Received-SPF: pass client-ip=2607:f8b0:4864:20::72e; envelope-from=casouri@gmail.com; helo=mail-qk1-x72e.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.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-mx.org@gnu.org Original-Sender: "Emacs-devel" Xref: news.gmane.io gmane.emacs.devel:273836 Archived-At: Here is the first page/node of tree-sitter=E2=80=99s manual, do you = think the third paragraph is redundant? It basically connects each menu = items together, but it also feels like just repeating the menu. And, = IIUC nodes are uniquely named in a manual, I think maybe it=E2=80=99s = not a good idea to use generic node names like =E2=80=9CLanguage = Definition=E2=80=9D, =E2=80=9CPattern Matching=E2=80=9D, etc, any = suggestions? The tree-sitter library (@uref{https://tree-sitter.github.io/tree-sitter/}) implements an incremental parser that supports a wide range of programming languages. A tree-sitter parser can generate and update a @dfn{concrete syntax tree}. In a syntax tree, text is no longer a one-dimensional stream but a structured tree of nodes, where each node representing a piece of text. Thus a syntax tree can enable interesting features like precise fontification and indentation, structured editing, etc. Apart from tree-sitter, Emacs provides a simple parsing facility for parsing balanced expressions. @xref{Parsing Expressions}. TODO: redundant? To access the syntax tree of the text in a buffer, we need to first load a language definition and create a parser with it. Next, we can query the parser for specific nodes in the syntax tree. Then, we can access various information about the node. Finally, we can pattern-match a node with a powerful syntax. The following sections explain how to do each of the tasks in detail. The last section compares the differences between tree-sitter's C API and the functions provided by Emacs Lisp, and the correspondence between all tree-sitter's C functions and their Emacs Lisp counterparts. @menu * Language Definitions:: Loading tree-sitter language definitions. * Using Parser:: Introduction to parsers. * Retrieving Node:: Retrieving node from syntax tree. * Accessing Node:: Accessing node information. * Pattern Matching:: Pattern matching with query patterns. * Multiple Languages:: Parse text written in multiple languages. * Tree-sitter C API:: A map from the C API to the ELisp API. @end menu Yuan