Mercurial > octave-dspies

comparison libinterp/parse-tree/oct-parse.in.yy @ 18531:04b4fb217b1a stable

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc: Improve documentation strings in parse-tree directory. * lex.ll (F__display_tokens__): Add seealso reference. * lex.ll (F__token_count__): Add seealso reference. * lex.ll (F__lexer_debug_flag__): Document function. * oct-parse.in.yy (Fautoload): Add additional calling form. Rephrase several sentences. * oct-parse.in.yy (Fmfilename): Make single sentence description stand apart from the rest of documentation. * oct-parse.in.yy (Fsource): Make single sentence description stand apart from the rest of documentation. Add seealso link to 'run'. * oct-parse.in.yy (Fbuiltin): Change type to "Built-in Function" from "Loadable Function". * oct-parse.in.yy (Feval): Rephrase several sentences. Add programming note suggesting the use of alternatives like try/catch or unwind_protect. * oct-parse.in.yy (F__parser_debug_flag__): Document function. * pt-mat.cc (Fstring_fill_char): Use semicolon in place of period for stronger idea linkage.
author Rik <rik@octave.org>
date Fri, 28 Feb 2014 14:04:41 -0800
parents 6b51f5f44aea
children 4cf930a64fad d8abf813c69f
comparison
equal deleted inserted replaced
18530:186ea1c2bbd4 18531:04b4fb217b1a
3707 return retval; 3707 return retval;
3708 } 3708 }
3709 3709
3710 DEFUN (autoload, args, , 3710 DEFUN (autoload, args, ,
3711 "-*- texinfo -*-\n\ 3711 "-*- texinfo -*-\n\
3712 @deftypefn {Built-in Function} {} autoload (@var{function}, @var{file})\n\ 3712 @deftypefn {Built-in Function} {@var{autoload_map} =} autoload ()\n\
3713 @deftypefnx {Built-in Function} {} autoload (@dots{}, @asis{\"remove\"})\n\ 3713 @deftypefnx {Built-in Function} {} autoload (@var{function}, @var{file})\n\
3714 @deftypefnx {Built-in Function} {} autoload (@dots{}, \"remove\")\n\
3714 Define @var{function} to autoload from @var{file}.\n\ 3715 Define @var{function} to autoload from @var{file}.\n\
3715 \n\ 3716 \n\
3716 The second argument, @var{file}, should be an absolute file name or\n\ 3717 The second argument, @var{file}, should be an absolute file name or\n\
3717 a file name in the same directory as the function or script from which\n\ 3718 a file name in the same directory as the function or script from which\n\
3718 the autoload command was run. @var{file} should not depend on the\n\ 3719 the autoload command was run. @var{file} @emph{should not} depend on the\n\
3719 Octave load path.\n\ 3720 Octave load path.\n\
3720 \n\ 3721 \n\
3721 Normally, calls to @code{autoload} appear in PKG_ADD script files that\n\ 3722 Normally, calls to @code{autoload} appear in PKG_ADD script files that\n\
3722 are evaluated when a directory is added to Octave's load path. To\n\ 3723 are evaluated when a directory is added to Octave's load path. To\n\
3723 avoid having to hardcode directory names in @var{file}, if @var{file}\n\ 3724 avoid having to hardcode directory names in @var{file}, if @var{file}\n\
3727 autoload (\"foo\", \"bar.oct\");\n\ 3728 autoload (\"foo\", \"bar.oct\");\n\
3728 @end example\n\ 3729 @end example\n\
3729 \n\ 3730 \n\
3730 @noindent\n\ 3731 @noindent\n\
3731 will load the function @code{foo} from the file @code{bar.oct}. The above\n\ 3732 will load the function @code{foo} from the file @code{bar.oct}. The above\n\
3732 usage when @code{bar.oct} is not in the same directory or usages such as\n\ 3733 usage when @code{bar.oct} is not in the same directory, or usages such as\n\
3733 \n\ 3734 \n\
3734 @example\n\ 3735 @example\n\
3735 autoload (\"foo\", file_in_loadpath (\"bar.oct\"))\n\ 3736 autoload (\"foo\", file_in_loadpath (\"bar.oct\"))\n\
3736 @end example\n\ 3737 @end example\n\
3737 \n\ 3738 \n\
3738 @noindent\n\ 3739 @noindent\n\
3739 are strongly discouraged, as their behavior may be unpredictable.\n\ 3740 are strongly discouraged, as their behavior may be unpredictable.\n\
3740 \n\ 3741 \n\
3741 With no arguments, return a structure containing the current autoload map.\n\ 3742 With no arguments, return a structure containing the current autoload map.\n\
3742 \n\ 3743 \n\
3743 If a third argument @asis{'remove'} is given, the function is cleared and\n\ 3744 If a third argument @qcode{\"remove\"} is given, the function is cleared and\n\
3744 not loaded anymore during the current Octave session.\n\ 3745 not loaded anymore during the current Octave session.\n\
3745 \n\ 3746 \n\
3746 @seealso{PKG_ADD}\n\ 3747 @seealso{PKG_ADD}\n\
3747 @end deftypefn") 3748 @end deftypefn")
3748 { 3749 {
3936 DEFUN (mfilename, args, , 3937 DEFUN (mfilename, args, ,
3937 "-*- texinfo -*-\n\ 3938 "-*- texinfo -*-\n\
3938 @deftypefn {Built-in Function} {} mfilename ()\n\ 3939 @deftypefn {Built-in Function} {} mfilename ()\n\
3939 @deftypefnx {Built-in Function} {} mfilename (\"fullpath\")\n\ 3940 @deftypefnx {Built-in Function} {} mfilename (\"fullpath\")\n\
3940 @deftypefnx {Built-in Function} {} mfilename (\"fullpathext\")\n\ 3941 @deftypefnx {Built-in Function} {} mfilename (\"fullpathext\")\n\
3941 Return the name of the currently executing file. At the top-level,\n\ 3942 Return the name of the currently executing file.\n\
3942 return the empty string. Given the argument @qcode{\"fullpath\"},\n\ 3943 \n\
3943 include the directory part of the file name, but not the extension.\n\ 3944 When called from outside an m-file return the empty string. Given the\n\
3944 Given the argument @qcode{\"fullpathext\"}, include the directory part\n\ 3945 argument @qcode{\"fullpath\"}, include the directory part of the file name,\n\
3945 of the file name and the extension.\n\ 3946 but not the extension. Given the argument @qcode{\"fullpathext\"}, include\n\
3947 the directory part of the file name and the extension.\n\
3946 @end deftypefn") 3948 @end deftypefn")
3947 { 3949 {
3948 octave_value retval; 3950 octave_value retval;
3949 3951
3950 int nargin = args.length (); 3952 int nargin = args.length ();
4002 } 4004 }
4003 4005
4004 DEFUN (source, args, , 4006 DEFUN (source, args, ,
4005 "-*- texinfo -*-\n\ 4007 "-*- texinfo -*-\n\
4006 @deftypefn {Built-in Function} {} source (@var{file})\n\ 4008 @deftypefn {Built-in Function} {} source (@var{file})\n\
4007 Parse and execute the contents of @var{file}. This is equivalent to\n\ 4009 Parse and execute the contents of @var{file}.\n\
4008 executing commands from a script file, but without requiring the file to\n\ 4010 \n\
4009 be named @file{@var{file}.m}.\n\ 4011 This is equivalent to executing commands from a script file, but without\n\
4012 requiring the file to be named @file{@var{file}.m}.\n\
4013 @seealso{run}\n\
4010 @end deftypefn") 4014 @end deftypefn")
4011 { 4015 {
4012 octave_value_list retval; 4016 octave_value_list retval;
4013 4017
4014 int nargin = args.length (); 4018 int nargin = args.length ();
4174 return retval; 4178 return retval;
4175 } 4179 }
4176 4180
4177 DEFUN (builtin, args, nargout, 4181 DEFUN (builtin, args, nargout,
4178 "-*- texinfo -*-\n\ 4182 "-*- texinfo -*-\n\
4179 @deftypefn {Loadable Function} {[@dots{}] =} builtin (@var{f}, @dots{})\n\ 4183 @deftypefn {Built-in Function} {[@dots{}] =} builtin (@var{f}, @dots{})\n\
4180 Call the base function @var{f} even if @var{f} is overloaded to\n\ 4184 Call the base function @var{f} even if @var{f} is overloaded to\n\
4181 another function for the given type signature.\n\ 4185 another function for the given type signature.\n\
4182 \n\ 4186 \n\
4183 This is normally useful when doing object-oriented programming and there\n\ 4187 This is normally useful when doing object-oriented programming and there\n\
4184 is a requirement to call one of Octave's base functions rather than\n\ 4188 is a requirement to call one of Octave's base functions rather than\n\
4341 Parse the string @var{try} and evaluate it as if it were an Octave\n\ 4345 Parse the string @var{try} and evaluate it as if it were an Octave\n\
4342 program. If that fails, evaluate the optional string @var{catch}.\n\ 4346 program. If that fails, evaluate the optional string @var{catch}.\n\
4343 The string @var{try} is evaluated in the current context,\n\ 4347 The string @var{try} is evaluated in the current context,\n\
4344 so any results remain available after @code{eval} returns.\n\ 4348 so any results remain available after @code{eval} returns.\n\
4345 \n\ 4349 \n\
4346 The following example makes the variable @var{A} with the approximate\n\ 4350 The following example creates the variable @var{A} with the approximate\n\
4347 value 3.1416 available.\n\ 4351 value of 3.1416 in the current workspace.\n\
4348 \n\ 4352 \n\
4349 @example\n\ 4353 @example\n\
4350 eval (\"A = acos(-1);\");\n\ 4354 eval (\"A = acos(-1);\");\n\
4351 @end example\n\ 4355 @end example\n\
4352 \n\ 4356 \n\
4353 If an error occurs during the evaluation of @var{try} the @var{catch}\n\ 4357 If an error occurs during the evaluation of @var{try} then the @var{catch}\n\
4354 string is evaluated, as the following example shows:\n\ 4358 string is evaluated, as the following example shows:\n\
4355 \n\ 4359 \n\
4356 @example\n\ 4360 @example\n\
4357 @group\n\ 4361 @group\n\
4358 eval ('error (\"This is a bad example\");',\n\ 4362 eval ('error (\"This is a bad example\");',\n\
4360 @print{} This error occurred:\n\ 4364 @print{} This error occurred:\n\
4361 This is a bad example\n\ 4365 This is a bad example\n\
4362 @end group\n\ 4366 @end group\n\
4363 @end example\n\ 4367 @end example\n\
4364 \n\ 4368 \n\
4365 Consider using try/catch blocks instead if you are only using @code{eval}\n\ 4369 Programming Note: if you are only using @code{eval} as an error-capturing\n\
4366 as an error-capturing mechanism rather than for the execution of arbitrary\n\ 4370 mechanism, rather than for the execution of arbitrary code strings,\n\
4367 code strings.\n\ 4371 Consider using try/catch blocks or unwind_protect/unwind_protect_cleanup\n\
4372 blocks instead. These techniques have higher performance and don't introduce\n\
4373 the security considerations that the evaluation of arbitrary code does.\n\
4368 @seealso{evalin}\n\ 4374 @seealso{evalin}\n\
4369 @end deftypefn") 4375 @end deftypefn")
4370 { 4376 {
4371 octave_value_list retval; 4377 octave_value_list retval;
4372 4378
4573 return retval; 4579 return retval;
4574 } 4580 }
4575 4581
4576 DEFUN (__parser_debug_flag__, args, nargout, 4582 DEFUN (__parser_debug_flag__, args, nargout,
4577 "-*- texinfo -*-\n\ 4583 "-*- texinfo -*-\n\
4578 @deftypefn {Built-in Function} {@var{old_val} =} __parser_debug_flag__ (@var{new_val}))\n\ 4584 @deftypefn {Built-in Function} {@var{val} =} __parser_debug_flag__ ()\n\
4579 Undocumented internal function.\n\ 4585 @deftypefnx {Built-in Function} {@var{old_val} =} __parser_debug_flag__ (@var{new_val})\n\
4586 Query or set the internal flag that determines whether Octave's parser prints\n\
4587 debug information as it processes an expression.\n\
4588 @seealso{__lexer_debug_flag__}\n\
4580 @end deftypefn") 4589 @end deftypefn")
4581 { 4590 {
4582 octave_value retval; 4591 octave_value retval;
4583 4592
4584 bool debug_flag = octave_debug; 4593 bool debug_flag = octave_debug;