Reply to topic  [ 5 posts ] 
about function 
Author Message
Yorick Master

Joined: Wed Jun 01, 2005 11:34 am
Posts: 112
Post about function
The about function can be used to search for and display documentation about two kinds of functions: interpreted and built-in. The code does this by calling symbol_names with an argument of 2096, which is the bit mask for interpreted functions (16), built-in functions (32), and the unknown bit 2048.

I suspect that third bit is actually supposed to be 1024, so that it would catch auto-loaded functions. If so, then there's a bug in std.i at line 270: "2096" should be replaced by "1072". If that's not a bug, then what is the undocumented 2048 bit for, and why aren't auto-load functions being included?

In addition to querying auto-loaded functions, the current about function also does not query opaque symbols and thus does not look at wrap_args functions and closure functions. Some of my locally defined functions fall into those categories, and thus for my usage, about is not searching all the functions I am interested in. I'm not sure if this is a bug or if it's working as intended?

For my own use, I would prefer to have about query all five kinds of functions. I have modified about locally so that it does this. Most of the work is in a utility function:

Code:
func find_functions(____f____) {
/* DOCUMENT find_functions();
         or find_functions(flags);
      Return an array of strings with the names of all symbols with the given
      function type(s) in the global symbol table. To select the type of
      symbol, FLAGS can be the bitwise-or of one or more of the following bits:
          1 - interpreted function symbols
          2 - built-in function symbols
          4 - auto-loaded function symbols
          8 - wrap_args function symbols
         16 - closure function symbols

      The special value FLAGS = -1 can be used to get all function names; this
      is also the behavior if FLAGS is nil or omitted.

    SEE ALSO: symbol_names, about
*/
  /* Implementation note: The FLAGS values are chosen so that they correspond
     to the return result of is_func, such that the return result of is_func
     indicates which bit needs to be set in FLAGS. This relationship is
     necessary to simplify the processing in the for loop below. */
  /* Attempt to use _very_ odd names to avoid clash with caller. */
  if(is_void(____f____) || ____f____ == -1) ____f____ = 31;
  // 1328 = 16 (interpreted) + 32 (builtin) + 256 (opaque) + 1024 (autoload)
  ____s____ = symbol_names(1328);
  // Not all opaque symbols are functions, so each symbol must be checked
  for(____i____ = 1; ____i____ <= numberof(____s____); ____i____++) {
    if(!is_func(symbol_def(____s____(____i____))))
      ____s____(____i____) = string(0);
    else if(!(____f____ & (2 ^ (is_func(symbol_def(____s____(____i____)))-1))))
      ____s____(____i____) = string(0);
  }
  return anyof(____s____) ? ____s____(where(____s____)) : [];
}


Then additionally, I modified the first line of code in the about function to replace these lines:
Code:
  /* Attempt to use _very_ odd names to avoid clash with caller. */
  ____a____ = symbol_names((____a____ ? -1 : 2096));

With these lines:
Code:
  /* Attempt to use _very_ odd names to avoid clash with caller. */
  ____a____ = ____a____ ? symbol_names(-1) : find_functions(-1);


Last edited by dnagle on Wed Jun 01, 2011 11:55 am, edited 1 time in total.



Wed May 25, 2011 6:41 am
Profile
Yorick Master

Joined: Mon Nov 22, 2004 9:43 am
Posts: 354
Location: Livermore, CA, USA
Post Re: about function
First, let me advertise a yorick design feature:
Code:
x(where(condition))

is exactly the same as:
Code:
anyof(condition)? x(where(condition)) : []

(in any context where the latter is legal).

Second, I can't make your modified about function work. For example:
Code:
> about,"vsave"
<not defined in an include file, running info function>
wrapped func vsave(args)


In fact, the help function does not work in conjunction with symbol_def, because to get the intended result, help needs a simple variable reference (something that could be returned as a result if it were an output argument). Thus,

Code:
> help,vsave
/* DOCUMENT c = vsave(var1, var2, ...);
          or c = vsave(var1, ..., string(namea), vara, ...);
----------snip-----------------
defined at:  LINE: 2743  FILE: /home/dave/gh/yorick/relocate/i0/std.i


but

Code:
> help,symbol_def("vsave")
<not defined in an include file, running info function>
wrapped func vsave(args)


I do not believe there is any workaround for this misfeature of the yorick help system. I know you are dissatisfied with yorick's help system and its level of introspection in general. I admit this is a weakness, and I hope to completely redesign the help system eventually, especially in light of the very good points you made in a previous discussion of the new "object oriented" features.

Introspection in yorick is much more problematic than the help function. Any function that uses calls to symbol_def, symbol_set, symbol_names, and the like, is pretty much doomed to give unintended results. So far, almost all code that uses these functions is intended to improve yorick's documentation system, or to provide generic GUI-type usability enhancements.

So my general plan is to completely overhaul the yorick help system, hopefully exposing the database to interpreted code. This is a very shallow kind of introspection, because it simply involves managing the DOCUMENT comment database -- the objects themselves are not really part of providing help. (Another way to say that is that you are merely using the objects as pointers to the help strings, not actually using their functionality. The symbol_def construct exposes their functionality, which is why it is evil.) Keep pointing out issues with yorick help, so we can be sure they get addressed in the overhaul. For the GUI-type enhancements, my plan is to actually provide a libglade package, which will be much more nearly what people want (but which will only be available on platforms that have GTK - all desktop machines, but not all compute servers).


Fri May 27, 2011 10:36 am
Profile
Yorick Master

Joined: Wed Jun 01, 2005 11:34 am
Posts: 112
Post Re: about function
For some reason I thought x(where(condition)) returned x when where(condition) returned <nuller>. That clearly isn't the case so I don't know where I picked that notion up.

I forgot to include a second change I made to the about function. At the end of the function, this line:
Code:
help, symbol_def(____a____);

Should get replaced by this line:
Code:
include, ["help, " + ____a____];

I suspect that may be just as evil as using symbol_def but it does appear to work. :)

We're using Tcl/Tk for our GUI needs, using a combination of Expect and fifo pipes to communicate between Tcl and Yorick. Do you anticipate that the changes you're planning to make will be advantageous to other GUI integrations such as this, or should we anticipate having to migrate to Glade/GTK at some point in the future?


Fri May 27, 2011 10:58 am
Profile
Yorick Guru

Joined: Thu May 10, 2007 12:07 pm
Posts: 62
Post Re: about function
Alternatively, if you have the last version of yorick with oxy object you can use the save command.
Code:
Ys = save(*);

Return an oxy object containing all defined variable. Then you can run a strgrep, for instance:
Code:
Ys = save(*);
ou = where( strgrep(  "your patern",  Ys(*,) );
if (!numberof(ou)) error, "nothing found";
if (numberof(ou)==1)  return help, Ys(ou(1));
else {
  Ys = Ys(noop(ou));
  ....  to be continued .... 

}


But you need to check if the symbol return a function.


Fri May 27, 2011 11:36 am
Profile
Yorick Master

Joined: Mon Nov 22, 2004 9:43 am
Posts: 354
Location: Livermore, CA, USA
Post Re: about function
:oops: I'm wrong! And on multiple counts! Thanks, guys, I stand corrected. I'll go ahead and patch up the about function. It looks like this use for the recent string-argument-to-include functionality can probably replace most if not all instances of symbol_def and symbol_set. The danger of this form of include is probably even greater, but strangely it seems more appropriate for this kind of thing. I have to admit I like it better.

As far as the GUI stuff goes, a fifo based system interfaced to Tcl/Tk will always work fine, so you will not need to change anything. The biggest reason I want an integrated GTK/glade system is to replace the current MFC-based system in yorick on MS Windows. The Windows version of yorick has fallen woefully out of date, partly because I can no longer build with MFC (my MFC-licensed compiler is obsolete, and using non-free software was a mistake).


Sun May 29, 2011 7:42 am
Profile
Display posts from previous:  Sort by  
Reply to topic   [ 5 posts ] 

Who is online

Users browsing this forum: No registered users and 1 guest


You cannot post new topics in this forum
You cannot reply to topics in this forum
You cannot edit your posts in this forum
You cannot delete your posts in this forum
You cannot post attachments in this forum

Search for:
Jump to:  
cron
Powered by phpBB © 2000, 2002, 2005, 2007 phpBB Group.
Designed by STSoftware for PTF.