Parametric categories: bug or documentation discrepancy

[unthingable]

Docs say:

These variables, the category parameters, can be accessed by calling the parameter/2 or this/1 built-in local methods in the category predicate clauses or by using parameter variables.

However:

:- category(functor(_Name, _Arity)).
    :- public(hi/0).
    hi :-
        this(This),
        self(Self),
        writeln(this-self-This-Self),
        writeln(vars-_Name-_Arity),
        parameter(1, N),
        parameter(2, A),
        writeln(params-N-A).

:- end_category.

:- object(testf(N,A), imports(functor(N, A))).
:- end_object.

?- testf(foo,1)::hi.
this-self-testf(foo,1)-testf(foo,1)
vars-_9212-_9206
params-foo-1
true.

Unless I'm mistaken:

• pamareter/2 indeed works as expected
• this/1 kind of works, would have expected it to be functor(foo, 1)
• parameter variables do not work

[pmoura]

There are no parameter variables in your example. Their syntax, as documented, requires their names to start and end with an underscore. Write _Name_ instead of _Name and _Arity_ instead of _Arity.

The this/1 built-in execution context method is working as intended, returning the object importing the category, as documented.

[unthingable]

Thanks! That fixes it.

In the examples I've seen parameters be _Name_, _Name and Name — was under the wrong impression that was a stylistic suggestion. Even the parametric category documentation lists this as an example immediately following the snippet above:

:- object(speech(Season, Event),
    imports([dress(Season), speech(Event)])).
    ...
:- end_object.

In parametric objects documentation states:

Object parameters can be accessed using parameter variables or built-in execution context methods. Parameter variables is the recommended solution to access object parameters. Although they introduce a concept of entity global variables, their unique syntax, ParameterName, avoids conflicts and makes them easily recognizable.

An explicit mention that this syntax is also required for named parameter var resolution to work would have made this clearer, I think.

[pmoura]

See also:

https://logtalk.org/manuals/userman/objects.html#accessing-object-parameters

Note that _Name is a named (but otherwise ) anonymous variable. Name is a variable that is expected to occur two or more times in a directive or clause (otherwise it will be reported as a singleton variable). Parameter variables are named anonymous variables that are recognized (and thus distinguished from other named anonymous variables) and specifically handled by the compiler thanks to their syntax. In that snippet, that syntax is not required as both Season and Event variables occur more than once.

I will look into improving the documentation. Thanks for the feedback.