Re: master 09b5f00613: ; Fix calls to treesit functions

Re: master 09b5f00613: ; Fix calls to treesit functions

[Stefan Monnier]

> +(declare-function treesit-available-p "treesit.c")
>  (declare-function treesit-parser-list "treesit.c")
>  (declare-function treesit-node-type "treesit.c")
>  
> @@ -156,7 +157,8 @@ or follows point."
>    (interactive "P")
>    (save-excursion
>      (let ((treesit-text-node
> -           (and (treesit-parser-list)
> +           (and (treesit-available-p)
> +                (treesit-parser-list)

How 'bout always defining `treesit-parser-list` (and making it return
`nil` if Emacs was compiled without Tree-sitter support)?

Most places that can make use of Tree-sitter probably would probably
prefer not to have to worry about the subtle distinction between
"Tree-sitter support is available but not for this major mode" and
"Tree-sitter support is not available at all".


        Stefan

Re: master 09b5f00613: ; Fix calls to treesit functions

[Yuan Fu]

> On Dec 18, 2022, at 12:19 PM, Stefan Monnier <monnier@iro.umontreal.ca> wrote:
> 
>> +(declare-function treesit-available-p "treesit.c")
>> (declare-function treesit-parser-list "treesit.c")
>> (declare-function treesit-node-type "treesit.c")
>> 
>> @@ -156,7 +157,8 @@ or follows point."
>>   (interactive "P")
>>   (save-excursion
>>     (let ((treesit-text-node
>> -           (and (treesit-parser-list)
>> +           (and (treesit-available-p)
>> +                (treesit-parser-list)
> 
> How 'bout always defining `treesit-parser-list` (and making it return
> `nil` if Emacs was compiled without Tree-sitter support)?
> 
> Most places that can make use of Tree-sitter probably would probably
> prefer not to have to worry about the subtle distinction between
> "Tree-sitter support is available but not for this major mode" and
> "Tree-sitter support is not available at all”.

That makes sense. Also, anyone using tree-sitter functions needs to declare functions in treesit.c in case Emacs didn’t build with tree-sitter. Should we streamline it with a macro like this? Would it work?

(defmacro treesit-declare-c-functions ()
  '(progn
     (declare-function treesit-node-child "treesit.c")
     ...))


(eval-when-compile
  (require 'treesit)
  (treesit-declare-c-functions))

Yuan

Re: master 09b5f00613: ; Fix calls to treesit functions

[Stefan Monnier]

> That makes sense.  Also, anyone using tree-sitter functions needs to
> declare functions in treesit.c in case Emacs didn’t build with
> tree-sitter.  Should we streamline it with a macro like this?

I wouldn't bother.

> (eval-when-compile
>   (require 'treesit)
>   (treesit-declare-c-functions))

`declare-function` within a `eval-when-compile` (just like (defvar
<foo>)) is a bad idea.  If it works, it's only by accident and can be
considered a bug (which could get fixed).


        Stefan

Re: master 09b5f00613: ; Fix calls to treesit functions

[Yuan Fu]

> On Dec 18, 2022, at 3:54 PM, Stefan Monnier <monnier@iro.umontreal.ca> wrote:
> 
>> That makes sense.  Also, anyone using tree-sitter functions needs to
>> declare functions in treesit.c in case Emacs didn’t build with
>> tree-sitter.  Should we streamline it with a macro like this?
> 
> I wouldn't bother.
> 
>> (eval-when-compile
>>  (require 'treesit)
>>  (treesit-declare-c-functions))
> 
> `declare-function` within a `eval-when-compile` (just like (defvar
> <foo>)) is a bad idea.  If it works, it's only by accident and can be
> considered a bug (which could get fixed).
> 

Cool, glad I asked ;-)

Yuan

Re: master 09b5f00613: ; Fix calls to treesit functions

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Cc: Eli Zaretskii <eliz@gnu.org>
> Date: Sun, 18 Dec 2022 15:19:53 -0500
> 
> How 'bout always defining `treesit-parser-list` (and making it return
> `nil` if Emacs was compiled without Tree-sitter support)?

Is it indeed guaranteed that the first function to be called by any
application that wants to optionally use tree-sitter will be
treesit-parser-list?  What if they want to start with some other
function?

Re: master 09b5f00613: ; Fix calls to treesit functions

[Stefan Monnier]

>> How 'bout always defining `treesit-parser-list` (and making it return
>> `nil` if Emacs was compiled without Tree-sitter support)?
> Is it indeed guaranteed that the first function to be called by any
> application that wants to optionally use tree-sitter will be
> treesit-parser-list?

Good question.  Tho I don't think we need a guarantee.
We just need it to be frequent enough.

> What if they want to start with some other function?

There's always `treesit-available-p`.


        Stefan

Re: master 09b5f00613: ; Fix calls to treesit functions

[Theodor Thornhill]

On 19 December 2022 04:37:03 CET, Stefan Monnier <monnier@iro.umontreal.ca> wrote:
>>> How 'bout always defining `treesit-parser-list` (and making it return
>>> `nil` if Emacs was compiled without Tree-sitter support)?
>> Is it indeed guaranteed that the first function to be called by any
>> application that wants to optionally use tree-sitter will be
>> treesit-parser-list? Av
>
>Good question.  Tho I don't think we need a guarantee.
>We just need it to be frequent enough.
>
>> What if they want to start with some other function?
>
>There's always `treesit-available-p`.
>
>
>        Stefan
1>
>

How about treesit-ensure, that checks treesit-available-p and whether it's enabled for the current mode? The treesit-parser-list is also kind of working just by accident, as it isn't its job to ensure availability.

Theo

Re: master 09b5f00613: ; Fix calls to treesit functions

[Yuan Fu]

> On Dec 18, 2022, at 10:26 PM, Theodor Thornhill <theo@thornhill.no> wrote:
> 
> 
> 
> On 19 December 2022 04:37:03 CET, Stefan Monnier <monnier@iro.umontreal.ca> wrote:
>>>> How 'bout always defining `treesit-parser-list` (and making it return
>>>> `nil` if Emacs was compiled without Tree-sitter support)?
>>> Is it indeed guaranteed that the first function to be called by any
>>> application that wants to optionally use tree-sitter will be
>>> treesit-parser-list? Av
>> 
>> Good question.  Tho I don't think we need a guarantee.
>> We just need it to be frequent enough.
>> 
>>> What if they want to start with some other function?
>> 
>> There's always `treesit-available-p`.
>> 
>> 
>>       Stefan
> 1>
>> 
> 
> How about treesit-ensure, that checks treesit-available-p and whether it's enabled for the current mode? The treesit-parser-list is also kind of working just by accident, as it isn't its job to ensure availability.

Depends on how you view it. If all you need to know is whether there is a parser and everything you do is language-agnostic, then checking treesit-parser-list is the right thing to do. 

OTOH treesit-ensure feels vague to me, what exactly does it represent? Treesit-available-p + treesit-parser-list? If it represents “this major mode is a tree-sitter mode”, it still doesn’t say much IMO. I think it makes more sense to check for specific features, eg, "is there a parser”.


Yuan

Re: master 09b5f00613: ; Fix calls to treesit functions

[Theodor Thornhill]

Yuan Fu <casouri@gmail.com> writes:

>> On Dec 18, 2022, at 10:26 PM, Theodor Thornhill <theo@thornhill.no> wrote:
>> 
>> 
>> 
>> On 19 December 2022 04:37:03 CET, Stefan Monnier <monnier@iro.umontreal.ca> wrote:
>>>>> How 'bout always defining `treesit-parser-list` (and making it return
>>>>> `nil` if Emacs was compiled without Tree-sitter support)?
>>>> Is it indeed guaranteed that the first function to be called by any
>>>> application that wants to optionally use tree-sitter will be
>>>> treesit-parser-list? Av
>>> 
>>> Good question.  Tho I don't think we need a guarantee.
>>> We just need it to be frequent enough.
>>> 
>>>> What if they want to start with some other function?
>>> 
>>> There's always `treesit-available-p`.
>>> 
>>> 
>>>       Stefan
>> 1>
>>> 
>> 
>> How about treesit-ensure, that checks treesit-available-p and whether it's enabled for the current mode? The treesit-parser-list is also kind of working just by accident, as it isn't its job to ensure availability.
>
> Depends on how you view it. If all you need to know is whether there
> is a parser and everything you do is language-agnostic, then checking
> treesit-parser-list is the right thing to do.
>
> OTOH treesit-ensure feels vague to me, what exactly does it represent?
> Treesit-available-p + treesit-parser-list? If it represents “this
> major mode is a tree-sitter mode”, it still doesn’t say much IMO. I
> think it makes more sense to check for specific features, eg, "is
> there a parser”.
>

Yeah, could be Treesit-available-p + treesit-parser-list.  It just feels
a little manual having to (and (treesit-available-p)
(treesit-parser-list) ...) every time we use it. Treesit-parser-ensure?

Theo

Re: master 09b5f00613: ; Fix calls to treesit functions

[Eli Zaretskii]

> Date: Mon, 19 Dec 2022 07:26:35 +0100
> From: Theodor Thornhill <theo@thornhill.no>
> 
> How about treesit-ensure, that checks treesit-available-p and whether it's enabled for the current mode? The treesit-parser-list is also kind of working just by accident, as it isn't its job to ensure availability.

Isn't that what treesit-language-available-p already does?

Re: master 09b5f00613: ; Fix calls to treesit functions

[Theodor Thornhill]

Eli Zaretskii <eliz@gnu.org> writes:

>> Date: Mon, 19 Dec 2022 07:26:35 +0100
>> From: Theodor Thornhill <theo@thornhill.no>
>> 
>> How about treesit-ensure, that checks treesit-available-p and whether it's enabled for the current mode? The treesit-parser-list is also kind of working just by accident, as it isn't its job to ensure availability.
>
> Isn't that what treesit-language-available-p already does?

Yeah, but I don't want to check for a particular language, only that
subsequent calls to treesit-functions will be available.

Theo

Re: master 09b5f00613: ; Fix calls to treesit functions

[Eli Zaretskii]

> From: Theodor Thornhill <theo@thornhill.no>
> Cc: emacs-devel@gnu.org, monnier@iro.umontreal.ca
> Date: Mon, 19 Dec 2022 14:47:24 +0100
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> >> Date: Mon, 19 Dec 2022 07:26:35 +0100
> >> From: Theodor Thornhill <theo@thornhill.no>
> >> 
> >> How about treesit-ensure, that checks treesit-available-p and whether it's enabled for the current mode? The treesit-parser-list is also kind of working just by accident, as it isn't its job to ensure availability.
> >
> > Isn't that what treesit-language-available-p already does?
> 
> Yeah, but I don't want to check for a particular language, only that
> subsequent calls to treesit-functions will be available.

You said:

  How about treesit-ensure, that checks treesit-available-p and
  whether it's enabled for the current mode?

If this check is for the current mode, then you already have the
"particular language", don't you?

And that is eventually the right test, because even if the tree-sitter
library is compiled in and available, the grammar library might not
be, which means the code cannot use tree-sitter in such a situation.

Re: master 09b5f00613: ; Fix calls to treesit functions

[Theodor Thornhill]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Theodor Thornhill <theo@thornhill.no>
>> Cc: emacs-devel@gnu.org, monnier@iro.umontreal.ca
>> Date: Mon, 19 Dec 2022 14:47:24 +0100
>> 
>> Eli Zaretskii <eliz@gnu.org> writes:
>> 
>> >> Date: Mon, 19 Dec 2022 07:26:35 +0100
>> >> From: Theodor Thornhill <theo@thornhill.no>
>> >> 
>> >> How about treesit-ensure, that checks treesit-available-p and whether it's enabled for the current mode? The treesit-parser-list is also kind of working just by accident, as it isn't its job to ensure availability.
>> >
>> > Isn't that what treesit-language-available-p already does?
>> 
>> Yeah, but I don't want to check for a particular language, only that
>> subsequent calls to treesit-functions will be available.
>
> You said:
>
>   How about treesit-ensure, that checks treesit-available-p and
>   whether it's enabled for the current mode?
>
> If this check is for the current mode, then you already have the
> "particular language", don't you?
>
> And that is eventually the right test, because even if the tree-sitter
> library is compiled in and available, the grammar library might not
> be, which means the code cannot use tree-sitter in such a situation.

Yeah, but in for example prog-mode I then have to do something like
(treesit-language-available-p (treesit-language-at (point)))

Which seems long.  IIRC I used something similar in an earlier patch,
and was dismissed because it should have its own api?

```
  (interactive "P")
  (save-excursion
    (if (or (and (treesit-available-p)
                 (treesit-ready-p (treesit-language-at (point)))
                 (string-match-p
                  treesit-comment-type-regexp
```

>>> For example, \"(line|block)_comment\". ")

>> The intent is that major modes set this variable?  SGTM.

>     (if (or (and (treesit-available-p)
>                  (treesit-ready-p (treesit-language-at (point)))

>> I'd imagine that this kind of test should have an API, so the
>> treesit-ready-p call should not be made explicitly?  Yuan, WDYT?
>> Also, isn't it enough to check whether the buffer has a tree-sitter
>> parser or something?

Theo

Re: master 09b5f00613: ; Fix calls to treesit functions

[Eli Zaretskii]

> From: Theodor Thornhill <theo@thornhill.no>
> Cc: emacs-devel@gnu.org, monnier@iro.umontreal.ca
> Date: Mon, 19 Dec 2022 15:51:22 +0100
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> >   How about treesit-ensure, that checks treesit-available-p and
> >   whether it's enabled for the current mode?
> >
> > If this check is for the current mode, then you already have the
> > "particular language", don't you?
> >
> > And that is eventually the right test, because even if the tree-sitter
> > library is compiled in and available, the grammar library might not
> > be, which means the code cannot use tree-sitter in such a situation.
> 
> Yeah, but in for example prog-mode I then have to do something like
> (treesit-language-available-p (treesit-language-at (point)))
> 
> Which seems long.

Maybe, but I think there's no way around it, if we want to include
tree-sitter code safely.

Yuan, Stefan, WDYT?

> IIRC I used something similar in an earlier patch,
> and was dismissed because it should have its own api?
> 
> ```
>   (interactive "P")
>   (save-excursion
>     (if (or (and (treesit-available-p)
>                  (treesit-ready-p (treesit-language-at (point)))

AFAIK, treesit-ready-p already calls treesit-available-p.

Re: master 09b5f00613: ; Fix calls to treesit functions

[Dmitry Gutov]

On 19/12/2022 17:21, Eli Zaretskii wrote:
>> Yeah, but in for example prog-mode I then have to do something like
>> (treesit-language-available-p (treesit-language-at (point)))
>>
>> Which seems long.
> Maybe, but I think there's no way around it, if we want to include
> tree-sitter code safely.

Why not make the LANGUAGE argument optional, and default to 
(treesit-language-at (point))?

Re: master 09b5f00613: ; Fix calls to treesit functions

[Theodor Thornhill]

On 19 December 2022 16:44:06 CET, Dmitry Gutov <dgutov@yandex.ru> wrote:
>On 19/12/2022 17:21, Eli Zaretskii wrote:
>>> Yeah, but in for example prog-mode I then have to do something like
>>> (treesit-language-available-p (treesit-language-at (point)))
>>> 
>>> Which seems long.
>> Maybe, but I think there's no way around it, if we want to include
>> tree-sitter code safely.
>
>Why not make the LANGUAGE argument optional, and default to (treesit-language-at (point))?

Sure :)
Theo

Re: master 09b5f00613: ; Fix calls to treesit functions

[Eli Zaretskii]

> Date: Mon, 19 Dec 2022 17:44:06 +0200
> Cc: emacs-devel@gnu.org, monnier@iro.umontreal.ca
> From: Dmitry Gutov <dgutov@yandex.ru>
> 
> On 19/12/2022 17:21, Eli Zaretskii wrote:
> >> Yeah, but in for example prog-mode I then have to do something like
> >> (treesit-language-available-p (treesit-language-at (point)))
> >>
> >> Which seems long.
> > Maybe, but I think there's no way around it, if we want to include
> > tree-sitter code safely.
> 
> Why not make the LANGUAGE argument optional, and default to 
> (treesit-language-at (point))?

There's no reason why not.

Yuan, WDYT?

Re: master 09b5f00613: ; Fix calls to treesit functions

[Stefan Monnier]

> The treesit-parser-list is also kind of working just by accident, as
> it isn't its job to ensure availability.

No, it's no accident: if Tree-sitter is not available, then indeed the
list of Tree-sitter parsers is empty.  So defining that function to return
nil when Tree-sitter is not available is a perfectly correct definition.


        Stefan

Re: master 09b5f00613: ; Fix calls to treesit functions

[Theodor Thornhill]

On 19 December 2022 17:13:00 CET, Stefan Monnier <monnier@iro.umontreal.ca> wrote:
>> The treesit-parser-list is also kind of working just by accident, as
>> it isn't its job to ensure availability.
>
>No, it's no accident: if Tree-sitter is not available, then indeed the
>list of Tree-sitter parsers is empty.  So defining that function to return
>nil when Tree-sitter is not available is a perfectly correct definition.
>
>
>        Stefan
>

Yeah, that's not what I meant. I meant that its primary purpose isn't too be used as a guard against treesit not being available at all. I'm fine with using it like this, but seeing how that wasn't enough by itself we should either change it or make a similar function that has that purpose. Fwiw I like your suggestion to make it available without treesit being available.

Theo

Re: master 09b5f00613: ; Fix calls to treesit functions

[Yuan Fu]

> On Dec 19, 2022, at 8:42 AM, Theodor Thornhill <theo@thornhill.no> wrote:
> 
> 
> 
> On 19 December 2022 17:13:00 CET, Stefan Monnier <monnier@iro.umontreal.ca> wrote:
>>> The treesit-parser-list is also kind of working just by accident, as
>>> it isn't its job to ensure availability.
>> 
>> No, it's no accident: if Tree-sitter is not available, then indeed the
>> list of Tree-sitter parsers is empty.  So defining that function to return
>> nil when Tree-sitter is not available is a perfectly correct definition.
>> 
>> 
>>       Stefan
>> 
> 
> Yeah, that's not what I meant. I meant that its primary purpose isn't too be used as a guard against treesit not being available at all. I'm fine with using it like this, but seeing how that wasn't enough by itself we should either change it or make a similar function that has that purpose. Fwiw I like your suggestion to make it available without treesit being available.
> 
> Theo
> 

I expect the vast majority uses of tree-sitter involves calling treesit-node-at (or treesit-node-on) to get a node, so that seems like a good place to add a check. And I’ll make them use (treesit-language-at (point)) by default, so that eliminates the need for checking for a particular language. In addition we can make treesit-parser-list work regardless of whether tree-sitter is built with Emacs. How does that sound?

Yuan

Re: master 09b5f00613: ; Fix calls to treesit functions

[Eli Zaretskii]

> From: Yuan Fu <casouri@gmail.com>
> Date: Mon, 19 Dec 2022 16:12:31 -0800
> Cc: Stefan Monnier <monnier@iro.umontreal.ca>,
>  emacs-devel@gnu.org,
>  Eli Zaretskii <eliz@gnu.org>
> 
> 
> I expect the vast majority uses of tree-sitter involves calling treesit-node-at (or treesit-node-on) to get a node, so that seems like a good place to add a check. And I’ll make them use (treesit-language-at (point)) by default, so that eliminates the need for checking for a particular language. In addition we can make treesit-parser-list work regardless of whether tree-sitter is built with Emacs. How does that sound?

SGTM, but I think we should document somewhere how does one write a
Lisp program that could optionally use tree-sitter, i.e. which APIs
text for the availability of tree-sitter support internally, and thus
could serve as a gate-keepers.

Re: master 09b5f00613: ; Fix calls to treesit functions

[Stefan Monnier]

> SGTM, but I think we should document somewhere how does one write a
> Lisp program that could optionally use tree-sitter, i.e. which APIs
> text for the availability of tree-sitter support internally, and thus
> could serve as a gate-keepers.

I think this can be done simply by listing which functions are always
defined.  Then we just have to make sure that those functions can be
implemented correctly even without Tree-sitter.  This is the case for
example for `treesit-node-at` and `treesit-parser-list` (where nil is
the correct answer when Tree-sitter is absent) .


        Stefan

Re: master 09b5f00613: ; Fix calls to treesit functions

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Cc: Yuan Fu <casouri@gmail.com>,  theo@thornhill.no,  emacs-devel@gnu.org
> Date: Mon, 19 Dec 2022 23:37:28 -0500
> 
> > SGTM, but I think we should document somewhere how does one write a
> > Lisp program that could optionally use tree-sitter, i.e. which APIs
> > text for the availability of tree-sitter support internally, and thus
> > could serve as a gate-keepers.
> 
> I think this can be done simply by listing which functions are always
> defined.

No, this is not enough, IMO.  What is needed in addition is to
document how to know, with each of these always-defined functions,
whether tree-sitter can be used (most probably, by examining the
returned value).

> Then we just have to make sure that those functions can be
> implemented correctly even without Tree-sitter.

The implementation without tree-sitter will probably be trivial, like
return nil or something like that.

Re: master 09b5f00613: ; Fix calls to treesit functions

[Stefan Monnier]

>> I think this can be done simply by listing which functions are always
>> defined.
>
> No, this is not enough, IMO.  What is needed in addition is to
> document how to know, with each of these always-defined functions,
> whether tree-sitter can be used (most probably, by examining the
> returned value).

That should be an obvious consequence of the behavior of the function
without needing to document it specifically.

Like with `treesit-parser-list`: if the list is empty, then it means we
don't have any parser at hand and that's it.  If the callers additionally
needs to know whether it's because Tree-sitter is absent or for some
other reason, they'll need to call additional functions like
`treesit-available-p`.

>> Then we just have to make sure that those functions can be
>> implemented correctly even without Tree-sitter.
> The implementation without tree-sitter will probably be trivial, like
> return nil or something like that.

Yes, but for some functions this is not an option because we can't
provide a correct behavior without using Tree-sitter.  So we have to
choose the set of always-defined functions based on whether they *can*
be correctly implemented without Tree-sitter.

`treesit-available-p`, `treesit-parser-list`, and `treesit-node-at` are
functions we can implement without Tree-sitter, because nil is already
the correct answer for those, without having to add any special
case in their docstring for that.


        Stefan

Re: master 09b5f00613: ; Fix calls to treesit functions

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Cc: casouri@gmail.com,  theo@thornhill.no,  emacs-devel@gnu.org
> Date: Tue, 20 Dec 2022 10:35:16 -0500
> 
> >> I think this can be done simply by listing which functions are always
> >> defined.
> >
> > No, this is not enough, IMO.  What is needed in addition is to
> > document how to know, with each of these always-defined functions,
> > whether tree-sitter can be used (most probably, by examining the
> > returned value).
> 
> That should be an obvious consequence of the behavior of the function
> without needing to document it specifically.
> 
> Like with `treesit-parser-list`: if the list is empty, then it means we
> don't have any parser at hand and that's it.

With functions returning a list, this is almost obvious, yes.  But
what about functions that return a buffer position, or a symbol, or
some other data type?  In those cases it is much less trivially
evident what to expect when tree-sitter support is unavailable.  Thus
the need to document this stuff.

> >> Then we just have to make sure that those functions can be
> >> implemented correctly even without Tree-sitter.
> > The implementation without tree-sitter will probably be trivial, like
> > return nil or something like that.
> 
> Yes, but for some functions this is not an option because we can't
> provide a correct behavior without using Tree-sitter.  So we have to
> choose the set of always-defined functions based on whether they *can*
> be correctly implemented without Tree-sitter.

Agreed.  My point was different, see abovge.

> `treesit-available-p`, `treesit-parser-list`, and `treesit-node-at` are
> functions we can implement without Tree-sitter, because nil is already
> the correct answer for those, without having to add any special
> case in their docstring for that.

If those are all that is needed, yes.

Re: master 09b5f00613: ; Fix calls to treesit functions

[Stefan Monnier]

> With functions returning a list, this is almost obvious, yes.  But
> what about functions that return a buffer position, or a symbol, or
> some other data type?  In those cases it is much less trivially
> evident what to expect when tree-sitter support is unavailable.

In such cases, the better choice may be not to provide an implementation
(or signal an error).

> Thus the need to document this stuff.

My take on it is that if we need to change the doc, then maybe this is
not a good candidate for the set of functions that are always defined :-)


        Stefan

Re: master 09b5f00613: ; Fix calls to treesit functions

[Yuan Fu]

> On Dec 20, 2022, at 8:02 AM, Stefan Monnier <monnier@iro.umontreal.ca> wrote:
> 
>> With functions returning a list, this is almost obvious, yes.  But
>> what about functions that return a buffer position, or a symbol, or
>> some other data type?  In those cases it is much less trivially
>> evident what to expect when tree-sitter support is unavailable.
> 
> In such cases, the better choice may be not to provide an implementation
> (or signal an error).
> 
>> Thus the need to document this stuff.
> 
> My take on it is that if we need to change the doc, then maybe this is
> not a good candidate for the set of functions that are always defined :-)

Technically there are only a handful of “entry functions”, ones that returns a node or parser which the user can further use, like treesit-node-at, treesit-parser-list. However many other functions that takes a node or parser as an argument also accepts a language symbol, or nil, for convenience. Maybe we can state explicitly that only functions that do not take a node or parser an an argument are always defined, and return nil when tree-sitter is not available. 


Yuan