Abstract objects should be able to describe their interactions

[yumaikas]

When dealing with JANET_ABSTRACT types at the REPL, there isn't an easy way get a notion of what sorts of things one can do with them.

Right now JANET_ABSTRACT types expose a Get() function pointer at the C level, that janet uses to translate method calls to them. But it's not easy/possible to get a list of the valid keys for Get().

One thing that would also be nice, in addition to getting a list of valid keys, would be setting aside one of those keys to get documentation from the object. For performance, I think it would make sense to not store the docs themselves on the object, but stash them away in a C constant, but it'd be nice to be able to have access to. Maybe via (doc-of ), that works by polling that key?

[yumaikas]

It might also be nice to implement (doc-of ) for other types as well, it'd make it awesome for learning, if you can expect to be able to (doc-of (value-from-library-i-do-not-know)) to dive in.

[bakpakin]

Via next there is already a mechanism got getting all available fields of an abstract type, however many of the built-in types don't implement this.

Not sure how doc-of would work - and I there is not reason I think for a new function, There is already (doc*) that is a function instead of a macro.

[bakpakin]

I suppose you could search through all bindings in all loaded libraries in module/cache for documentation you are looking for, which should give a pretty exhaustive search.

[yumaikas]

Would you like some help getting next implemented for the various built-in types? Where are good places to look for that?

[pepe]

I guess there is not a lot of fruits still hanging.

[bakpakin]

On latest master, added an implementation of doc-of - dfbdd17

[yumaikas]

I'll take it for a spin tomorrow

[sogaiu]

Just putting the nice example from @yumaikas here from the channel:

(doc-of ((file/temp) :read))

[MikeBeller]

Hey @bakpakin I assumed the reason for :next method in abstract types was to allow someone to build an iterable abstract type. Like say I want to create (btree/new ....) I really don't want :next then to be the methods of the abstract type. It should be the records in the b-tree, in order. If a convention of finding the methods of an abstract type is using (next) then we have a situation where my hypothetical b-tree will confuse people. And really it shouldn't. The way to find the methods of something should rather be something like (each (type-of (btree/new...) ...

[pepe]

I do not know @bakpakin's reasons, but what I got is that it returns its methods on the abstract types in the core that do not have meaningful iterations. For your own type, it can be whatever you want (including the methods :).

But only my impression tho.

[MikeBeller]

Yes but this means next is not a reliable way to determine the methods of an abstract object. Because sometimes it works and sometimes it doesn't. Very confusing to my mind.

[bakpakin]

This is a very good point, and even in the core it applies to typed arrays (tarray/*), as became obvious when implementing this change. It was mostly just an oversight - I guess an abstract type may have multiple "ranges" of keys - for example, all of the available methods and a sequence of indices, and next might not want to traverse all of them.

I like the idea of the type-of function, which could return a table for any abstract type. It would also return the table prototype for tables to get the same behavior. As for the name, we have a function that is very similar to this already - table/getproto. We could extend (table/getproto) to work on abstract types if needed, and say, return nil for any unsupported types to make it work for all janet values (since it would no longer just accept tables).

This would probably best be done by adding a new member to the JanetAbstractType structure. I have been trying to avoid adding more members to this structure, so we could also using a standard method (:getproto abstract-type) to do this, but in this particular case I think the function pointer is actually easier to use.

Clearly, there are several ways to do this.

[MikeBeller]

Can this also "unify" with the idea of allowing people to create their own abstract types directly in Janet using prototypes? I.e. I create my hypothetical b-tree with a Janet table as the base structure, and in the table's prototype I can have a :_next method and a :_marshal method, etc? And if so is it best to overload table/getproto, or just make a couple of "abstract/" calls, like (abstract/new ...) (abstract/getmethods ...) -- just a thought.

[yumaikas]

We could move getproto from table/ to type/ or take the prefix off entirely