comparison src/eval.c @ 40141:3bb2c22854a2

(Frun_hooks, Frun_hook_with_args, Frun_hook_with_args_until_failure) (Frun_hook_with_args_until_success, Ffuncall, For, Fand, Fif, Fcond) (Fprogn, Fprog1, Fprog2, Fsetq, Fquote, Ffunction, Fdefun, Fdefmacro) (Fdefvar, Fdefconst, FletX, Flet, Fwhile, Fcatch, Funwind_protect) (Fcondition_case): Add usage: string to doc string.

40140:9bf80d5fff41

   The definition of `For' shows what you have to do.  */

DEFUN ("or", For, Sor, 0, UNEVALLED, 0,
  "Eval args until one of them yields non-nil, then return that value.\n\
The remaining args are not evalled at all.\n\
If all args return nil, return nil.")
  (args)
     Lisp_Object args;
{
  register Lisp_Object val;
  Lisp_Object args_left;

}

DEFUN ("and", Fand, Sand, 0, UNEVALLED, 0,
  "Eval args until one of them yields nil, then return nil.\n\
The remaining args are not evalled at all.\n\
If no arg yields nil, return the last arg's value.")
  (args)
     Lisp_Object args;
{
  register Lisp_Object val;
  Lisp_Object args_left;

DEFUN ("if", Fif, Sif, 2, UNEVALLED, 0,
  "If COND yields non-nil, do THEN, else do ELSE...\n\
Returns the value of THEN or the value of the last of the ELSE's.\n\
THEN must be one expression, but ELSE... can be zero or more expressions.\n\
If COND yields nil, and there are no ELSE's, the value is nil.")
  (args)
     Lisp_Object args;
{
  register Lisp_Object cond;
  struct gcpro gcpro1;

and, if the value is non-nil, this clause succeeds:\n\
then the expressions in BODY are evaluated and the last one's\n\
value is the value of the cond-form.\n\
If no clause succeeds, cond returns nil.\n\
If a clause has one element, as in (CONDITION),\n\
CONDITION's value if non-nil is returned from the cond-form.")
  (args)
     Lisp_Object args;
{
  register Lisp_Object clause, val;
  struct gcpro gcpro1;

  return val;
}

DEFUN ("progn", Fprogn, Sprogn, 0, UNEVALLED, 0,
  "Eval BODY forms sequentially and return value of last one.")
  (args)
     Lisp_Object args;
{
  register Lisp_Object val, tem;
  Lisp_Object args_left;

}

DEFUN ("prog1", Fprog1, Sprog1, 1, UNEVALLED, 0,
  "Eval FIRST and BODY sequentially; value from FIRST.\n\
The value of FIRST is saved during the evaluation of the remaining args,\n\
whose values are discarded.")
  (args)
     Lisp_Object args;
{
  Lisp_Object val;
  register Lisp_Object args_left;

}

DEFUN ("prog2", Fprog2, Sprog2, 2, UNEVALLED, 0,
  "Eval X, Y and BODY sequentially; value from Y.\n\
The value of Y is saved during the evaluation of the remaining args,\n\
whose values are discarded.")
  (args)
     Lisp_Object args;
{
  Lisp_Object val;
  register Lisp_Object args_left;

The symbols SYM are variables; they are literal (not evaluated).\n\
The values VAL are expressions; they are evaluated.\n\
Thus, (setq x (1+ y)) sets `x' to the value of `(1+ y)'.\n\
The second VAL is not computed until after the first SYM is set, and so on;\n\
each VAL can use the new value of variables set earlier in the `setq'.\n\
The return value of the `setq' form is the value of the last VAL.")
  (args)
     Lisp_Object args;
{
  register Lisp_Object args_left;
  register Lisp_Object val, sym;

  UNGCPRO;
  return val;
}
     
DEFUN ("quote", Fquote, Squote, 1, UNEVALLED, 0,
  "Return the argument, without evaluating it.  `(quote x)' yields `x'.")
  (args)
     Lisp_Object args;
{
  return Fcar (args);
}
     
DEFUN ("function", Ffunction, Sfunction, 1, UNEVALLED, 0,
  "Like `quote', but preferred for objects which are functions.\n\
In byte compilation, `function' causes its argument to be compiled.\n\
`quote' cannot do that.")
  (args)
     Lisp_Object args;
{
  return Fcar (args);
}

DEFUN ("defun", Fdefun, Sdefun, 2, UNEVALLED, 0,
  "Define NAME as a function.\n\
The definition is (lambda ARGLIST [DOCSTRING] BODY...).\n\
See also the function `interactive'.")
  (args)
     Lisp_Object args;
{
  register Lisp_Object fn_name;
  register Lisp_Object defn;

  "Define NAME as a macro.\n\
The definition is (macro lambda ARGLIST [DOCSTRING] BODY...).\n\
When the macro is called, as in (NAME ARGS...),\n\
the function (lambda ARGLIST BODY...) is applied to\n\
the list ARGS... as it appears in the expression,\n\
and the result should be a form to be evaluated instead of the original.")
  (args)
     Lisp_Object args;
{
  register Lisp_Object fn_name;
  register Lisp_Object defn;

 buffer-local values are not affected.\n\
INITVALUE and DOCSTRING are optional.\n\
If DOCSTRING starts with *, this variable is identified as a user option.\n\
 This means that M-x set-variable recognizes it.\n\
 See also `user-variable-p'.\n\
If INITVALUE is missing, SYMBOL's value is not set.")
  (args)
     Lisp_Object args;
{
  register Lisp_Object sym, tem, tail;

  "Define SYMBOL as a constant variable.\n\
The intent is that neither programs nor users should ever change this value.\n\
Always sets the value of SYMBOL to the result of evalling INITVALUE.\n\
If SYMBOL is buffer-local, its default value is what is set;\n\
 buffer-local values are not affected.\n\
DOCSTRING is optional.")
  (args)
     Lisp_Object args;
{
  register Lisp_Object sym, tem;

DEFUN ("let*", FletX, SletX, 1, UNEVALLED, 0,
  "Bind variables according to VARLIST then eval BODY.\n\
The value of the last form in BODY is returned.\n\
Each element of VARLIST is a symbol (which is bound to nil)\n\
or a list (SYMBOL VALUEFORM) (which binds SYMBOL to the value of VALUEFORM).\n\
Each VALUEFORM can refer to the symbols already bound by this VARLIST.")
  (args)
     Lisp_Object args;
{
  Lisp_Object varlist, val, elt;
  int count = specpdl_ptr - specpdl;

DEFUN ("let", Flet, Slet, 1, UNEVALLED, 0,
  "Bind variables according to VARLIST then eval BODY.\n\
The value of the last form in BODY is returned.\n\
Each element of VARLIST is a symbol (which is bound to nil)\n\
or a list (SYMBOL VALUEFORM) (which binds SYMBOL to the value of VALUEFORM).\n\
All the VALUEFORMs are evalled before any symbols are bound.")
  (args)
     Lisp_Object args;
{
  Lisp_Object *temps, tem;
  register Lisp_Object elt, varlist;

}

DEFUN ("while", Fwhile, Swhile, 1, UNEVALLED, 0,
  "If TEST yields non-nil, eval BODY... and repeat.\n\
The order of execution is thus TEST, BODY, TEST, BODY and so on\n\
until TEST returns nil.")
  (args)
     Lisp_Object args;
{
  Lisp_Object test, body, tem;
  struct gcpro gcpro1, gcpro2;

TAG is evalled to get the tag to use; it must not be nil.\n\
\n\
Then the BODY is executed.\n\
Within BODY, (throw TAG) with same tag exits BODY and exits this `catch'.\n\
If no throw happens, `catch' returns the value of the last BODY form.\n\
If a throw happens, it specifies the value to return from `catch'.")
  (args)
     Lisp_Object args;
{
  register Lisp_Object tag;
  struct gcpro gcpro1;

DEFUN ("unwind-protect", Funwind_protect, Sunwind_protect, 1, UNEVALLED, 0,
  "Do BODYFORM, protecting with UNWINDFORMS.\n\
If BODYFORM completes normally, its value is returned\n\
after executing the UNWINDFORMS.\n\
If BODYFORM exits nonlocally, the UNWINDFORMS are executed anyway.")
  (args)
     Lisp_Object args;
{
  Lisp_Object val;
  int count = specpdl_ptr - specpdl;

control returns to the condition-case and the handler BODY... is executed\n\
with VAR bound to (SIGNALED-CONDITIONS . SIGNAL-DATA).\n\
VAR may be nil; then you do not get access to the signal information.\n\
\n\
The value of the last BODY form is returned from the condition-case.\n\
See also the function `signal' for more info.")
  (args)
     Lisp_Object args;
{
  Lisp_Object val;
  struct catchtag c;

}

DEFUN ("apply", Fapply, Sapply, 2, MANY, 0,
  "Call FUNCTION with our remaining args, using our last arg as list of args.\n\
Then return the value FUNCTION returns.\n\
Thus, (apply '+ 1 2 '(3 4)) returns 10.")
  (nargs, args)
     int nargs;
     Lisp_Object *args;
{
  register int i, numargs;

or a list of functions to be called to run the hook.\n\
If the value is a function, it is called with no arguments.\n\
If it is a list, the elements are called, in order, with no arguments.\n\
\n\
To make a hook variable buffer-local, use `make-local-hook',\n\
not `make-local-variable'.")
  (nargs, args)
     int nargs;
     Lisp_Object *args;
{
  Lisp_Object hook[1];

with the given arguments ARGS.\n\
It is best not to depend on the value return by `run-hook-with-args',\n\
as that may change.\n\
\n\
To make a hook variable buffer-local, use `make-local-hook',\n\
not `make-local-variable'.")
  (nargs, args)
     int nargs;
     Lisp_Object *args;
{
  return run_hook_with_args (nargs, args, to_completion);

passing arguments ARGS to each of them, until one of them\n\
returns a non-nil value.  Then we return that value.\n\
If all the functions return nil, we return nil.\n\
\n\
To make a hook variable buffer-local, use `make-local-hook',\n\
not `make-local-variable'.")
  (nargs, args)
     int nargs;
     Lisp_Object *args;
{
  return run_hook_with_args (nargs, args, until_success);

passing arguments ARGS to each of them, until one of them\n\
returns nil.  Then we return nil.\n\
If all the functions return non-nil, we return non-nil.\n\
\n\
To make a hook variable buffer-local, use `make-local-hook',\n\
not `make-local-variable'.")
  (nargs, args)
     int nargs;
     Lisp_Object *args;
{
  return run_hook_with_args (nargs, args, until_failure);

}

DEFUN ("funcall", Ffuncall, Sfuncall, 1, MANY, 0,
  "Call first argument as a function, passing remaining arguments to it.\n\
Return the value that function returns.\n\
Thus, (funcall 'cons 'x 'y) returns (x . y).")
  (nargs, args)
     int nargs;
     Lisp_Object *args;
{
  Lisp_Object fun;

40141:3bb2c22854a2

   The definition of `For' shows what you have to do.  */

DEFUN ("or", For, Sor, 0, UNEVALLED, 0,
  "Eval args until one of them yields non-nil, then return that value.\n\
The remaining args are not evalled at all.\n\
If all args return nil, return nil.\n\
usage: (or CONDITIONS ...)")
  (args)
     Lisp_Object args;
{
  register Lisp_Object val;
  Lisp_Object args_left;

}

DEFUN ("and", Fand, Sand, 0, UNEVALLED, 0,
  "Eval args until one of them yields nil, then return nil.\n\
The remaining args are not evalled at all.\n\
If no arg yields nil, return the last arg's value.\n\
usage: (and CONDITIONS ...)")
  (args)
     Lisp_Object args;
{
  register Lisp_Object val;
  Lisp_Object args_left;

DEFUN ("if", Fif, Sif, 2, UNEVALLED, 0,
  "If COND yields non-nil, do THEN, else do ELSE...\n\
Returns the value of THEN or the value of the last of the ELSE's.\n\
THEN must be one expression, but ELSE... can be zero or more expressions.\n\
If COND yields nil, and there are no ELSE's, the value is nil.\n\
usage: (if COND THEN ELSE...)")
  (args)
     Lisp_Object args;
{
  register Lisp_Object cond;
  struct gcpro gcpro1;

and, if the value is non-nil, this clause succeeds:\n\
then the expressions in BODY are evaluated and the last one's\n\
value is the value of the cond-form.\n\
If no clause succeeds, cond returns nil.\n\
If a clause has one element, as in (CONDITION),\n\
CONDITION's value if non-nil is returned from the cond-form.\n\
usage: (cond CLAUSES...)")
  (args)
     Lisp_Object args;
{
  register Lisp_Object clause, val;
  struct gcpro gcpro1;

  return val;
}

DEFUN ("progn", Fprogn, Sprogn, 0, UNEVALLED, 0,
  "Eval BODY forms sequentially and return value of last one.\n\
usage: (progn BODY ...)")
  (args)
     Lisp_Object args;
{
  register Lisp_Object val, tem;
  Lisp_Object args_left;

}

DEFUN ("prog1", Fprog1, Sprog1, 1, UNEVALLED, 0,
  "Eval FIRST and BODY sequentially; value from FIRST.\n\
The value of FIRST is saved during the evaluation of the remaining args,\n\
whose values are discarded.\n\
usage: (prog1 FIRST BODY...)")
  (args)
     Lisp_Object args;
{
  Lisp_Object val;
  register Lisp_Object args_left;

}

DEFUN ("prog2", Fprog2, Sprog2, 2, UNEVALLED, 0,
  "Eval X, Y and BODY sequentially; value from Y.\n\
The value of Y is saved during the evaluation of the remaining args,\n\
whose values are discarded.\n\
usage: (prog2 X Y BODY...)")
  (args)
     Lisp_Object args;
{
  Lisp_Object val;
  register Lisp_Object args_left;

The symbols SYM are variables; they are literal (not evaluated).\n\
The values VAL are expressions; they are evaluated.\n\
Thus, (setq x (1+ y)) sets `x' to the value of `(1+ y)'.\n\
The second VAL is not computed until after the first SYM is set, and so on;\n\
each VAL can use the new value of variables set earlier in the `setq'.\n\
The return value of the `setq' form is the value of the last VAL.\n\
usage: (setq SYM VAL SYM VAL ...)")
  (args)
     Lisp_Object args;
{
  register Lisp_Object args_left;
  register Lisp_Object val, sym;

  UNGCPRO;
  return val;
}
     
DEFUN ("quote", Fquote, Squote, 1, UNEVALLED, 0,
  "Return the argument, without evaluating it.  `(quote x)' yields `x'.\n\
usage: (quote ARG)")
  (args)
     Lisp_Object args;
{
  return Fcar (args);
}
     
DEFUN ("function", Ffunction, Sfunction, 1, UNEVALLED, 0,
  "Like `quote', but preferred for objects which are functions.\n\
In byte compilation, `function' causes its argument to be compiled.\n\
`quote' cannot do that.\n\
usage: (function ARG)")
  (args)
     Lisp_Object args;
{
  return Fcar (args);
}

DEFUN ("defun", Fdefun, Sdefun, 2, UNEVALLED, 0,
  "Define NAME as a function.\n\
The definition is (lambda ARGLIST [DOCSTRING] BODY...).\n\
See also the function `interactive'.\n\
usage: (defun NAME ARGLIST [DOCSTRING] BODY...)")
  (args)
     Lisp_Object args;
{
  register Lisp_Object fn_name;
  register Lisp_Object defn;

  "Define NAME as a macro.\n\
The definition is (macro lambda ARGLIST [DOCSTRING] BODY...).\n\
When the macro is called, as in (NAME ARGS...),\n\
the function (lambda ARGLIST BODY...) is applied to\n\
the list ARGS... as it appears in the expression,\n\
and the result should be a form to be evaluated instead of the original.\n\
usage: (defmacro NAME ARGLIST [DOCSTRING] BODY...)")
  (args)
     Lisp_Object args;
{
  register Lisp_Object fn_name;
  register Lisp_Object defn;

 buffer-local values are not affected.\n\
INITVALUE and DOCSTRING are optional.\n\
If DOCSTRING starts with *, this variable is identified as a user option.\n\
 This means that M-x set-variable recognizes it.\n\
 See also `user-variable-p'.\n\
If INITVALUE is missing, SYMBOL's value is not set.\n\
usage: (defvar SYMBOL [INITVALUE DOCSTRING])")
  (args)
     Lisp_Object args;
{
  register Lisp_Object sym, tem, tail;

  "Define SYMBOL as a constant variable.\n\
The intent is that neither programs nor users should ever change this value.\n\
Always sets the value of SYMBOL to the result of evalling INITVALUE.\n\
If SYMBOL is buffer-local, its default value is what is set;\n\
 buffer-local values are not affected.\n\
DOCSTRING is optional.\n\
usage: (defconst SYMBOL INITVALUE [DOCSTRING])")
  (args)
     Lisp_Object args;
{
  register Lisp_Object sym, tem;

DEFUN ("let*", FletX, SletX, 1, UNEVALLED, 0,
  "Bind variables according to VARLIST then eval BODY.\n\
The value of the last form in BODY is returned.\n\
Each element of VARLIST is a symbol (which is bound to nil)\n\
or a list (SYMBOL VALUEFORM) (which binds SYMBOL to the value of VALUEFORM).\n\
Each VALUEFORM can refer to the symbols already bound by this VARLIST.\n\
usage: (let* VARLIST BODY...)")
  (args)
     Lisp_Object args;
{
  Lisp_Object varlist, val, elt;
  int count = specpdl_ptr - specpdl;

DEFUN ("let", Flet, Slet, 1, UNEVALLED, 0,
  "Bind variables according to VARLIST then eval BODY.\n\
The value of the last form in BODY is returned.\n\
Each element of VARLIST is a symbol (which is bound to nil)\n\
or a list (SYMBOL VALUEFORM) (which binds SYMBOL to the value of VALUEFORM).\n\
All the VALUEFORMs are evalled before any symbols are bound.\n\
usage: (let VARLIST BODY...)")
  (args)
     Lisp_Object args;
{
  Lisp_Object *temps, tem;
  register Lisp_Object elt, varlist;

}

DEFUN ("while", Fwhile, Swhile, 1, UNEVALLED, 0,
  "If TEST yields non-nil, eval BODY... and repeat.\n\
The order of execution is thus TEST, BODY, TEST, BODY and so on\n\
until TEST returns nil.\n\
usage: (while TEST BODY...)")
  (args)
     Lisp_Object args;
{
  Lisp_Object test, body, tem;
  struct gcpro gcpro1, gcpro2;

TAG is evalled to get the tag to use; it must not be nil.\n\
\n\
Then the BODY is executed.\n\
Within BODY, (throw TAG) with same tag exits BODY and exits this `catch'.\n\
If no throw happens, `catch' returns the value of the last BODY form.\n\
If a throw happens, it specifies the value to return from `catch'.\n\
usage: (catch TAG BODY...)")
  (args)
     Lisp_Object args;
{
  register Lisp_Object tag;
  struct gcpro gcpro1;

DEFUN ("unwind-protect", Funwind_protect, Sunwind_protect, 1, UNEVALLED, 0,
  "Do BODYFORM, protecting with UNWINDFORMS.\n\
If BODYFORM completes normally, its value is returned\n\
after executing the UNWINDFORMS.\n\
If BODYFORM exits nonlocally, the UNWINDFORMS are executed anyway.\n\
usage: (unwind-protect BODYFORM UNWINDFORMS...)")
  (args)
     Lisp_Object args;
{
  Lisp_Object val;
  int count = specpdl_ptr - specpdl;

control returns to the condition-case and the handler BODY... is executed\n\
with VAR bound to (SIGNALED-CONDITIONS . SIGNAL-DATA).\n\
VAR may be nil; then you do not get access to the signal information.\n\
\n\
The value of the last BODY form is returned from the condition-case.\n\
See also the function `signal' for more info.\n\
usage: (condition-case VAR BODYFORM HANDLERS...)")
  (args)
     Lisp_Object args;
{
  Lisp_Object val;
  struct catchtag c;

}

DEFUN ("apply", Fapply, Sapply, 2, MANY, 0,
  "Call FUNCTION with our remaining args, using our last arg as list of args.\n\
Then return the value FUNCTION returns.\n\
Thus, (apply '+ 1 2 '(3 4)) returns 10.\n\
usage: (apply FUNCTION &rest ARGUMENTS)")
  (nargs, args)
     int nargs;
     Lisp_Object *args;
{
  register int i, numargs;

or a list of functions to be called to run the hook.\n\
If the value is a function, it is called with no arguments.\n\
If it is a list, the elements are called, in order, with no arguments.\n\
\n\
To make a hook variable buffer-local, use `make-local-hook',\n\
not `make-local-variable'.\n\
usage: (run-hooks &rest HOOKS)")
  (nargs, args)
     int nargs;
     Lisp_Object *args;
{
  Lisp_Object hook[1];

with the given arguments ARGS.\n\
It is best not to depend on the value return by `run-hook-with-args',\n\
as that may change.\n\
\n\
To make a hook variable buffer-local, use `make-local-hook',\n\
not `make-local-variable'.\n\
usage: (run-hook-with-args HOOK &rest ARGS)")
  (nargs, args)
     int nargs;
     Lisp_Object *args;
{
  return run_hook_with_args (nargs, args, to_completion);

passing arguments ARGS to each of them, until one of them\n\
returns a non-nil value.  Then we return that value.\n\
If all the functions return nil, we return nil.\n\
\n\
To make a hook variable buffer-local, use `make-local-hook',\n\
not `make-local-variable'.\n\
usage: (run-hook-with-args-until-success HOOK &rest ARGS)")
  (nargs, args)
     int nargs;
     Lisp_Object *args;
{
  return run_hook_with_args (nargs, args, until_success);

passing arguments ARGS to each of them, until one of them\n\
returns nil.  Then we return nil.\n\
If all the functions return non-nil, we return non-nil.\n\
\n\
To make a hook variable buffer-local, use `make-local-hook',\n\
not `make-local-variable'.\n\
usage: (run-hook-with-args-until-failure HOOK &rest ARGS)")
  (nargs, args)
     int nargs;
     Lisp_Object *args;
{
  return run_hook_with_args (nargs, args, until_failure);

}

DEFUN ("funcall", Ffuncall, Sfuncall, 1, MANY, 0,
  "Call first argument as a function, passing remaining arguments to it.\n\
Return the value that function returns.\n\
Thus, (funcall 'cons 'x 'y) returns (x . y).\n\
usage: (funcall FUNCTION &rest ARGUMENTS)")
  (nargs, args)
     int nargs;
     Lisp_Object *args;
{
  Lisp_Object fun;