plDoc and whitelisting

[Anniepoo]

It would be quite convenient if plDoc generated html included some indication of which predicates were whitelisted.

Visually, we distinguish predicate types with gold vs light blue vs dark blue, etc. - maybe some elaboration of this scheme, or some icons, could do it

Not sure what we do about their being potentially more than one application. Nor am I sure what to do about things that are conditionally whitelisted.

[wouterbeek]

@Anniepoo Can you define these categories for me? I see labels (1) gold, (2) light blue, (3) dark blue, (4) maybe more? These are related to categories (1) whitelisted, (2) conditionally whitelisted, (3) other?

If plDoc can discover the category based on parsing some Prolog file then the HTML rendition can include semantic RDFa annotations that describe this part of the semantics unambiguously.

[Anniepoo]

the backgrounds of predicates are something like gold - multifile dark bLue - public light blue - private

I think there's a second yellow tone for dynamic

another good plae to somehow display this is the editor.

[wouterbeek]

@Anniepoo Thanks for specifying the categories. But how do these interact with whitelisting? Not all public predicates should be whitelisted IIUC.

[Anniepoo]

Well, shell is public, I hope we're not whitelisting it.

If you look at sources of pldoc pages, you'll see that the dt that defines the predicate header has a class set.

this class is pubdef for public predicates, multidef for multifile public predicates privdef for private predicates (you'll have to do this in the local doc server).

[wouterbeek]

@Anniepoo shell/1 would be defined as pubdef according to the following code in doc_html.pl:

(   private(Obj, Options)
->  Class = privdef     % private definition
;   multifile(Obj, Options)
->  (   option(scope(file), Options)
    ->  (   more_doc(Obj, Pos)
    ->  Class = multidef(object(Obj))
    ;   Class = multidef
    )
    ;   Class = multidef(file((Pos)))
    )
;   Class = pubdef      % public definition
),

If shell/1 is not whitelisted then this information must be stored somewhere else?

[Anniepoo]

Yes, of course it would. Technically, predicates aren't just whitelisted. safe_predicate can look at the args, so foo(2) could be safe but foo(3) not. I think there's a list of whitelisted system predicates somehwere, but I'm too busy with other stuff today to go looking for it.

[JanWielemaker]

Yip. You can basically just do safe_goal(Head), using the most generic head. If that succeeds it is whitelisted, but indeed if it fails it may work with specific arguments. This is notably a problem for meta-predicates, which will not pass as safe without instantiating their arguments to something safe. That could be automated (find meta-arguments and instantiate them. I'd be tempted to use an icon to indicate safety rather than yet another colour. This might actually also be a good idea for multifile predicates as both are orthogonal to public/private.

[Anniepoo]

Yes, the icon's a good idea. I'll draw one

[Anniepoo]

Would implementing this imply loading pengines library, and if so, are we creating a security issue? If added to pldoc, simply starting the doc_server could expose a general pengine server. Doing this without warning might be bad.

[JanWielemaker]

No. You only need to load library(sandbox).

[Anniepoo]

ah, cool