Executing function only if another function is defined

Executing function only if another function is defined

[carlmarcos--- via Users list for the GNU Emacs text editor]

The following function appends additional text to the `docstring' of the function `toucan'.

Because it may be possible that some functions are not available (e.g. during testing or debugging phases), I would like to test whether the function `toucan' has been defined before I call `docboost'.  What can I do? 

(defun toucan-usage ()
  "TODO"
   
  (docboost 'toucan "Usage Information"))

RE: [External] : Executing function only if another function is defined

[Drew Adams]

[-- Attachment #1: Type: text/plain, Size: 7193 bytes --]

> I would like to test whether the function `toucan'
> has been defined before I call `docboost'.
> What can I do?

Defined where?  By who/what?  What's the context?

Predefined as part of Emacs?  Defined in some
3rd-party package?  Defined in some library that
you've already loaded in the current session?

Defined under the name `toucan'?  Defined under
another name (or anonymously) but with the same
code or similar behavior?

A Lisp function, i.e., funcallable?  A "function"
more generally (a "function-like object"), i.e.,
a symbol with a non-nil `symbol-function' value?
___

-- Function: functionp object
This function returns ‘t’ if OBJECT is any kind of function, i.e.,
can be passed to ‘funcall’.  Note that ‘functionp’ returns ‘t’ for
symbols that are function names, and returns ‘nil’ for special
forms.

-- Function: fboundp symbol
This function returns ‘t’ if the symbol has an object in its
function cell, ‘nil’ otherwise.  It does not check that the object
is a legitimate function.

-- Function: symbol-function symbol
This returns the object in the function cell of SYMBOL.  It does
not check that the returned object is a legitimate function.

If the function cell is void, the return value is ‘nil’.  To
distinguish between a function cell that is void and one set to
‘nil’, use ‘fboundp’ (see below).
...

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 the symbol
as a function, Emacs 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’.
___

FWIW -

Your questions tend to be guessing games for
anyone who might want to help.  (What is it that
he's asking?  Is it bigger than a bread basket?
Animal?  Vegetable?  Mineral?)

Do _yourself_ a favor and _ask yourself_ first
what it is that you really want to ask.

Getting an answer starts with understanding
your own question.  If you can't explicate your
question then you don't really understand what
you're asking, as well as you should.  Asking
it (badly) at that point can waste your time as
well as that of others.
___

Elisp manual menu, node `Functions':

13 Functions
************

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.
* Generic Functions::           Polymorphism, Emacs-style.
* Function Cells::              Accessing or setting the function definition
                            of a symbol.
* Closures::                    Functions that enclose a lexical environment.
* Advising Functions::          Adding to the definition of a function.
* Obsolete Functions::          Declaring functions obsolete.
* Inline Functions::            Functions that the compiler will expand inline.
* Declare Form::                Adding additional information about a function.
* Declaring Functions::         Telling the compiler that a function is defined.
* Function Safety::             Determining whether a function is safe to call.
* Related Topics::              Cross-references to specific Lisp primitives
                            that have a special bearing on how functions work.
___

Elisp manual `Index', entries starting with
"function" (all with completion from `i'):

* funcall:                               Calling Functions.   (line  22)
* funcall <1>:                           Module Misc.         (line  56)
* funcall, and debugging:                Internals of Debugger.
                                                              (line  86)
* funcall-interactively:                 Interactive Call.    (line  73)
* function:                              Anonymous Functions. (line  39)
* function aliases:                      Defining Functions.  (line  53)
* function call:                         Function Forms.      (line   6)
* function call debugging:               Function Debugging.  (line   6)
* function cell:                         Symbol Components.   (line  16)
* function cell in autoload:             Autoload.            (line  70)
* function declaration:                  Declaring Functions. (line   6)
* function definition:                   Function Names.      (line   6)
* function descriptions:                 A Sample Function Description.
                                                              (line   6)
* function form evaluation:              Function Forms.      (line   6)
* function input stream:                 Input Streams.       (line  26)
* function invocation:                   Calling Functions.   (line   6)
* function keys:                         Function Keys.       (line   6)
* function name:                         Function Names.      (line   6)
* function not known to be defined, compilation warning: Compiler Errors.
                                                              (line  21)
* function output stream:                Output Streams.      (line  24)
* function quoting:                      Anonymous Functions. (line  40)
* function safety:                       Function Safety.     (line   6)
* function-documentation property:       Documentation Basics.
                                                              (line  12)
* function-get:                          Symbol Plists.       (line  58)
* function-put:                          Symbol Plists.       (line  68)
* functionals:                           Calling Functions.   (line 107)
* functionp:                             What Is a Function.  (line  95)
* functions in modes:                    Major Mode Conventions.
                                                              (line  55)
* functions, making them interactive:    Defining Commands.   (line   6)
___

Someone has gone to a lot of trouble to lay
out for you the answers to your questions.
You just need to learn how to _Ask Emacs_.
And then try your best to do that.

[-- Attachment #2: winmail.dat --]
[-- Type: application/ms-tnef, Size: 16172 bytes --]

RE: [External] : Executing function only if another function is defined

[carlmarcos--- via Users list for the GNU Emacs text editor]

Jul 24, 2022, 14:33 by drew.adams@oracle.com:

>> I would like to test whether the function `toucan'
>> has been defined before I call `docboost'.
>> What can I do?
>>
>
> Defined where?  By who/what?  What's the context?
>
> Predefined as part of Emacs?  Defined in some
> 3rd-party package?  Defined in some library that
> you've already loaded in the current session?
>
> Defined under the name `toucan'?  Defined under
> another name (or anonymously) but with the same
> code or similar behavior?
>

I define the function toucan in one of my init files using (require 'myfile)

Sometimes I comment out the require part, meaning that the function toucan would not be loaded.  Thus it does not make sense to a information to its docstring.



> A Lisp function, i.e., funcallable?  A "function"
> more generally (a "function-like object"), i.e.,
> a symbol with a non-nil `symbol-function' value?
>
>
>
> ___
>
> -- Function: functionp object
> This function returns ‘t’ if OBJECT is any kind of function, i.e.,
> can be passed to ‘funcall’.  Note that ‘functionp’ returns ‘t’ for
> symbols that are function names, and returns ‘nil’ for special
> forms.
>
> -- Function: fboundp symbol
> This function returns ‘t’ if the symbol has an object in its
> function cell, ‘nil’ otherwise.  It does not check that the object
> is a legitimate function.
>
> -- Function: symbol-function symbol
> This returns the object in the function cell of SYMBOL.  It does
> not check that the returned object is a legitimate function.
>
> If the function cell is void, the return value is ‘nil’.  To
> distinguish between a function cell that is void and one set to
> ‘nil’, use ‘fboundp’ (see below).
> ...
>
> 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 the symbol
> as a function, Emacs 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’.
> ___
>
> FWIW -
>
> Your questions tend to be guessing games for
> anyone who might want to help.  (What is it that
> he's asking?  Is it bigger than a bread basket?
> Animal?  Vegetable?  Mineral?)
>
> Do _yourself_ a favor and _ask yourself_ first
> what it is that you really want to ask.
>
> Getting an answer starts with understanding
> your own question.  If you can't explicate your
> question then you don't really understand what
> you're asking, as well as you should.  Asking
> it (badly) at that point can waste your time as
> well as that of others.
> ___
>
> Elisp manual menu, node `Functions':
>
> 13 Functions
> ************
>
> 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.
> * Generic Functions::           Polymorphism, Emacs-style.
> * Function Cells::              Accessing or setting the function definition
>  of a symbol.
> * Closures::                    Functions that enclose a lexical environment.
> * Advising Functions::          Adding to the definition of a function.
> * Obsolete Functions::          Declaring functions obsolete.
> * Inline Functions::            Functions that the compiler will expand inline.
> * Declare Form::                Adding additional information about a function.
> * Declaring Functions::         Telling the compiler that a function is defined.
> * Function Safety::             Determining whether a function is safe to call.
> * Related Topics::              Cross-references to specific Lisp primitives
>  that have a special bearing on how functions work.
> ___
>
> Elisp manual `Index', entries starting with
> "function" (all with completion from `i'):
>
> * funcall:                               Calling Functions.   (line  22)
> * funcall <1>:                           Module Misc.         (line  56)
> * funcall, and debugging:                Internals of Debugger.
>  (line  86)
> * funcall-interactively:                 Interactive Call.    (line  73)
> * function:                              Anonymous Functions. (line  39)
> * function aliases:                      Defining Functions.  (line  53)
> * function call:                         Function Forms.      (line   6)
> * function call debugging:               Function Debugging.  (line   6)
> * function cell:                         Symbol Components.   (line  16)
> * function cell in autoload:             Autoload.            (line  70)
> * function declaration:                  Declaring Functions. (line   6)
> * function definition:                   Function Names.      (line   6)
> * function descriptions:                 A Sample Function Description.
>  (line   6)
> * function form evaluation:              Function Forms.      (line   6)
> * function input stream:                 Input Streams.       (line  26)
> * function invocation:                   Calling Functions.   (line   6)
> * function keys:                         Function Keys.       (line   6)
> * function name:                         Function Names.      (line   6)
> * function not known to be defined, compilation warning: Compiler Errors.
>  (line  21)
> * function output stream:                Output Streams.      (line  24)
> * function quoting:                      Anonymous Functions. (line  40)
> * function safety:                       Function Safety.     (line   6)
> * function-documentation property:       Documentation Basics.
>  (line  12)
> * function-get:                          Symbol Plists.       (line  58)
> * function-put:                          Symbol Plists.       (line  68)
> * functionals:                           Calling Functions.   (line 107)
> * functionp:                             What Is a Function.  (line  95)
> * functions in modes:                    Major Mode Conventions.
>  (line  55)
> * functions, making them interactive:    Defining Commands.   (line   6)
> ___
>
> Someone has gone to a lot of trouble to lay
> out for you the answers to your questions.
> You just need to learn how to _Ask Emacs_.
> And then try your best to do that.
>

Re: Executing function only if another function is defined

[Emanuel Berg]

carlmarcos--- via Users list for the GNU Emacs text editor wrote:

> Because it may be possible that some functions are not
> available (e.g. during testing or debugging phases), I would
> like to test whether the function `toucan' has been defined
> before I call `docboost'. What can I do?
>
> (defun toucan-usage ()
>   "TODO"
>
>   (docboost 'toucan "Usage Information"))

(Why are you using no-break space?)

What you can do?

You can ...

1. `require' the library where "toucan" is defined.

2. Use the hash/sharp-quote, #', instead of just the quote for
   toucan. (#' is `function' and ' is `quote' BTW.)

3. Byte-compile. The byte compiler will tell you if toucan
   is undefined.

-- 
underground experts united
https://dataswamp.org/~incal

Re: [External] : Executing function only if another function is defined

[Emanuel Berg]

carlmarcos--- via Users list for the GNU Emacs text editor wrote:

> I define the function toucan in one of my init files using
> (require 'myfile)

Good.

> Sometimes I comment out the require part, meaning that the
> function toucan would not be loaded.

Why?

> Thus it does not make sense to a information to
> its docstring.

If you brake the code intentionally I don't know what does
make sense actually ... fix it and don't do it again?

-- 
underground experts united
https://dataswamp.org/~incal

help as a function of a NEWS problem (was: Re: Executing function only if another function is defined)

[Emanuel Berg]

> 2. Use the hash/sharp-quote, #', instead of just the quote for
>    toucan. (#' is `function' and ' is `quote' BTW.)

Do C-h f function RET and hit the 1.1 button.

Is that why it is called "Probably introduced"?

It just makes a search for the first time the name appears
in NEWS?

But, I see the `...' convention in that file, so why not
search for `function' instead? Then there won't be a hit.

(Yeah, how can that make sense? Search for X instead because
then there won't be a hit ...)

-- 
underground experts united
https://dataswamp.org/~incal

Re: Executing function only if another function is defined

[carlmarcos--- via Users list for the GNU Emacs text editor]

Jul 25, 2022, 01:39 by incal@dataswamp.org:

> carlmarcos--- via Users list for the GNU Emacs text editor wrote:
>
>> Because it may be possible that some functions are not
>> available (e.g. during testing or debugging phases), I would
>> like to test whether the function `toucan' has been defined
>> before I call `docboost'. What can I do?
>>
>> (defun toucan-usage ()
>>  "TODO"
>>
>>  (docboost 'toucan "Usage Information"))
>>
>
> (Why are you using no-break space?)
>
> What you can do?
>
> You can ...
>
> 1. `require' the library where "toucan" is defined.
>
> 2. Use the hash/sharp-quote, #', instead of just the quote for
>  toucan. (#' is `function' and ' is `quote' BTW.)
>
> 3. Byte-compile. The byte compiler will tell you if toucan
>  is undefined.
>
I have modified the function as follows

(defun docboost (fname doc-boost)
  "Appends a string to the documentation of a function.
FNAME       Name of function
DOC-BOOST   Documentation"

  (if (functionp fname)
      (put fname 'function-documentation
   (concat (documentation fname t) doc-boost))))

Then doing as you suggest with

(typex-docboost #'toucan "Additional Text:")

Is `functionp' appropriate for testing whether `fname' was defined?

Adding a newline before printing the additional documentation would be a sensible thing to do.
How to do it within docboost?

Re: Executing function only if another function is defined

[Emanuel Berg]

carlmarcos--- via Users list for the GNU Emacs text editor wrote:

> (defun docboost (fname doc-boost)
>   "Appends a string to the documentation of a function.
> FNAME     Name of function
> DOC-BOOST Documentation"

Nice!

It should be automated to appear like that by default and
automatically, and incorrect docstrings shouldn't not just be
"considered" bugs, they should be bugs ...

Well, automated - one would still have to write (and read)
the information manually ...

However the first argument's name is perhaps not so good as
its inclusion of "name" implies it is a string, better to call
that just "fun" perhaps. And not just for fun ...

The second argument's isn't so good either as the "boost"
suffix doesn't add anything. Maybe call it "doc" or
"str" instead?

> (if (functionp fname)
>   (put fname 'function-documentation
>        (concat (documentation fname t) doc-boost))))

`when'

> Is `functionp' appropriate for testing whether `fname'
> was defined?

I don't see why not?

> Adding a newline before printing the additional
> documentation would be a sensible thing to do. How to do it
> within docboost?

"\n"

-- 
underground experts united
https://dataswamp.org/~incal

Re: Executing function only if another function is defined

[carlmarcos--- via Users list for the GNU Emacs text editor]

Jul 25, 2022, 11:14 by incal@dataswamp.org:

> carlmarcos--- via Users list for the GNU Emacs text editor wrote:
>
>> (defun docboost (fname doc-boost)
>>  "Appends a string to the documentation of a function.
>> FNAME     Name of function
>> DOC-BOOST Documentation"
>>
>
> Nice!
>
> It should be automated to appear like that by default and
> automatically, and incorrect docstrings shouldn't not just be
> "considered" bugs, they should be bugs ...
>
What don't you agree with exactly?  The docstring in the function
definition would only be a brief description.  If additional information 
in required, that can be added later, as not to encumber the function with
too much text before one can start seeing the implementation.


> Well, automated - one would still have to write (and read)
> the information manually ...
>
> However the first argument's name is perhaps not so good as
> its inclusion of "name" implies it is a string, better to call
> that just "fun" perhaps. And not just for fun ...
>
> The second argument's isn't so good either as the "boost"
> suffix doesn't add anything. Maybe call it "doc" or
> "str" instead?
>
>> (if (functionp fname)
>>  (put fname 'function-documentation
>>  (concat (documentation fname t) doc-boost))))
>>
>
> `when'
>
>> Is `functionp' appropriate for testing whether `fname'
>> was defined?
>>
>
> I don't see why not?
>
 In case there is a superior way to test whether the function was
defined.


>> Adding a newline before printing the additional
>> documentation would be a sensible thing to do. How to do it
>> within docboost?
>>
>
> "\n"
>
> -- 
> underground experts united
> https://dataswamp.org/~incal
>

Re: Executing function only if another function is defined

[Emanuel Berg]

carlmarcos--- via Users list for the GNU Emacs text editor wrote:

>>> (defun docboost (fname doc-boost)
>>>  "Appends a string to the documentation of a function.
>>> FNAME     Name of function
>>> DOC-BOOST Documentation"
>>
>> Nice!
>>
>> It should be automated to appear like that by default and
>> automatically, and incorrect docstrings shouldn't not just be
>> "considered" bugs, they should be bugs ...
>
> What don't you agree with exactly? The docstring in the
> function definition would only be a brief description.
> If additional information in required, that can be added
> later, as not to encumber the function with too much text
> before one can start seeing the implementation.

?????????

>> I don't see why not?
>
> In case there is a superior way to test whether the function
> was defined.

Uhm ... is there a difference between the questions "is
X a function" and "is X defined as a function"?

-- 
underground experts united
https://dataswamp.org/~incal

Re: Executing function only if another function is defined

[carlmarcos--- via Users list for the GNU Emacs text editor]

-- 
 Sent with Tutanota, enjoy secure & ad-free emails. 



Jul 25, 2022, 11:45 by incal@dataswamp.org:

> carlmarcos--- via Users list for the GNU Emacs text editor wrote:
>
>>>> (defun docboost (fname doc-boost)
>>>>  "Appends a string to the documentation of a function.
>>>> FNAME     Name of function
>>>> DOC-BOOST Documentation"
>>>>
>>>
>>> Nice!
>>>
>>> It should be automated to appear like that by default and
>>> automatically, and incorrect docstrings shouldn't not just be
>>> "considered" bugs, they should be bugs ...
>>>
>>
>> What don't you agree with exactly? The docstring in the
>> function definition would only be a brief description.
>> If additional information in required, that can be added
>> later, as not to encumber the function with too much text
>> before one can start seeing the implementation.
>>
>
> ?????????
>
I refer you to your remark about automation.  Was it a criticism?


>>> I don't see why not?
>>>
>>
>> In case there is a superior way to test whether the function
>> was defined.
>>
>
> Uhm ... is there a difference between the questions "is
> X a function" and "is X defined as a function"?
>
Because there is also fboundp and symbol-function.