Browser information

[Waldek Hebisch]

I have now commited a package that exposes infomation equivalent
to used by Hyperdoc browser. There are still some troubles,
but returned information is good enough to support almost all
functionality of current Hyperdoc. It can also be used to
produce API HTML pages, there is some degradation compared
to what Ralf's package produces, mainly conditions may be
more complicated than needed and some origins are suboptimal.
But the best thing with conditions would be to simplify them
in the Spad compiler.

Anyway, currently this package is unused and likely to change,
but I think that it is useful even in its current form.

--
Waldek Hebisch

[Ralf Hemmecke]

On 1/5/26 14:21, Waldek Hebisch wrote:
> I have now commited a package that exposes infomation equivalent
> to used by Hyperdoc browser.

Would it make sense, if I try to rewrite api.spad so that any "$Lisp" is
replaced by the respective function from your new package?

> to what Ralf's package produces, mainly conditions may be
> more complicated than needed and some origins are suboptimal.
> But the best thing with conditions would be to simplify them
> in the Spad compiler.

If the compiler (erm, actually some fricas function or your package)
would already return a simplified expression for the conditions that
would be perfect. Otherwise, I think ConstructorData (and friends) from
api.spad could be used.

Ralf

[Waldek Hebisch]

On Tue, Jan 06, 2026 at 01:10:16AM +0100, 'Ralf Hemmecke' via FriCAS - computer algebra system wrote:
> On 1/5/26 14:21, Waldek Hebisch wrote:
> > I have now commited a package that exposes infomation equivalent
> > to used by Hyperdoc browser.
>
> Would it make sense, if I try to rewrite api.spad so that any "$Lisp" is
> replaced by the respective function from your new package?

It would be good to move to common representation. But this is
much more than "$Lisp" calls. Actually AFAICS api.spad make
relatively small number of "$Lisp" calls.

> > to what Ralf's package produces, mainly conditions may be
> > more complicated than needed and some origins are suboptimal.
> > But the best thing with conditions would be to simplify them
> > in the Spad compiler.
>
> If the compiler (erm, actually some fricas function or your package) would
> already return a simplified expression for the conditions that would be
> perfect. Otherwise, I think ConstructorData (and friends) from api.spad
> could be used.

Some simplifcations to work at all must be done pretty early.
Basically, once we put unsimplified condition on a signature in
a category if may be impossible to simplify it at later stages.
I mean, a condition in isolation can not be simplified and
simplification is possible only because the source (category)
that introduced given signature and we can simplify condition
on the involved category. Which means that good simplification
either will be in Spad compiler or must re-do work done by Spad
compiler. So doing work in Spad compiler looks better to me. But
Spad compiler is doing other things and fitting simplifications
here is not so easy. Still, in long term having several pieces of
code doing similar, but not identical things lead to increased
maintenence work, so I want to move simplifications to such
places that they can be used as widely as possible.

--
Waldek Hebisch

[Ralf Hemmecke]

> It would be good to move to common representation. But this is much
> more than "$Lisp" calls. Actually AFAICS api.spad make relatively
> small number of "$Lisp" calls.

I always try to keep lisp calls to a minimum. So if I could shift them
all to your package and can achieve the same functionality, that would
be great.

I must admit that api.spad was born out of my desire to produce the api
webpage. My datastructure are more adhoc for exactly that purpose. If
you now come up with something more general or you put allow discussions
on your ideas, then there will certainly be a datastructure (and
respective accessor functions) be created that makes everyone happy.

> Some simplifcations to work at all must be done pretty early.
> Basically, once we put unsimplified condition on a signature in a
> category if may be impossible to simplify it at later stages.

Sorry, but I don't understand it.
When code from api.spad is executed, there is a compiled FriCAS behind,
so all the information must be somewhere otherwise the comiler/
interpreter would not be able to deal with the condition.

The condition resolution that I implemented (sorry it's long time ago
that I actually looked at it) only deals with the information that comes
from the get_database $ Lisp calls. It must then investigate whether the
parameters of the category/domain/package lead to some simplifications
for the conditions. If such simplifications could be handled by some
low-level function, that would be great. I bet the interpreter/compiler
also must do such simplifications in order to check which function to
call or whether the function is exported at all. So, if this
interpreter/compiler functionality could be made available to the spad-
level, that would also be great an not require to duplicate such code.
But maybe, my knowledge of the internals is too weak to say anything
reasonable here.

> I mean, a condition in isolation can not be simplified and
> simplification is possible only because the source (category) that
> introduced given signature and we can simplify condition on the
> involved category. Which means that good simplification either will
> be in Spad compiler or must re-do work done by Spad compiler. So
> doing work in Spad compiler looks better to me.

Yes, understood and supported. For resolving conditions, a global view
is needed.

> But Spad compiler is doing other things and fitting simplifications
> here is not so easy. Still, in long term having several pieces of
> code doing similar, but not identical things lead to increased
> maintenence work, so I want to move simplifications to such places
> that they can be used as widely as possible.

OK, looks like we are on the same side.
I hoped the condition-simplification-code is already quite separate from
the rest of the compiler.

In total, nobody wants that HyperDoc is showing other conditions than
fricas.github.io/api and the interpreter/compiler yet behaves in another
way. They should all use the same mechanism, of course.

Ralf

[Waldek Hebisch]

On Tue, Jan 06, 2026 at 03:54:21PM +0100, 'Ralf Hemmecke' via FriCAS - computer algebra system wrote:
> > It would be good to move to common representation. But this is much
> > more than "$Lisp" calls. Actually AFAICS api.spad make relatively
> > small number of "$Lisp" calls.
>
> I always try to keep lisp calls to a minimum. So if I could shift them
> all to your package and can achieve the same functionality, that would
> be great.
>
> I must admit that api.spad was born out of my desire to produce the api
> webpage. My datastructure are more adhoc for exactly that purpose. If
> you now come up with something more general or you put allow discussions
> on your ideas, then there will certainly be a datastructure (and
> respective accessor functions) be created that makes everyone happy.

Concerning datastructures, if you (or somebody else) thinks that
we need different datastructures or some impovement, then I am
happy to discuss this.

I came to current datastructures in BrowserInformation due to
following considerations. First, at low level for efficiency
we use symbols instead of strings, so to keep things consistent
and avoid converting back and forth I used symbols too (unless
there were other reason to prefer strings). I kept signatures
mostly as in existing Boot code, that is as a list with retrurn
type first and arguments after that. Also for conditions I kept
representation from lower level. For display we want info
about origin and documentation string, so we essentially get
Sig_doc record. One could discuss if this record should contain
also function name. That is almost arbitrary decision, in some
places it is convenient to group functions "by name", that is
for each name have list of possibilities. In other places we
want to process name together with other data. Hyperdoc allows
grouping in other ways, for this I introduced Grp_rec.

For constructors we do not have overloading, so constructor is
uniquely identified by its name. So we can represent list of
constructors by list of symbols. Since at various places
we shows separately info abound different kinds, I introduced
Split_rec. Gen_rec is to represent result of general search
(both constructors and operations). Searches use patterns
and some patterns are not valid, so we need some indication
about possible errors. Current Boot code puts an error
message in case of error in pattern, so I kept Boot representation
(but having type as a macro partially abstracts this).

In some places we need constructors with conditions. Conditions
may refer to constructor parameters, so for this I use "constructor
form", that is list with constructor name as first element,
followed by arguments.

Hyperdoc in many places shows exposure information. But exposure
is really info about constructor names and can be recomputed
at reasonable cost. So I do not put exposure information in
data structures, instead 'exposed_constructor?' allows
retriving it when needed.

> > Some simplifcations to work at all must be done pretty early. Basically,
> > once we put unsimplified condition on a signature in a
> > category if may be impossible to simplify it at later stages.
>
> Sorry, but I don't understand it.
> When code from api.spad is executed, there is a compiled FriCAS behind,
> so all the information must be somewhere otherwise the comiler/
> interpreter would not be able to deal with the condition.

Well, compiler dully makes OR-s or AND-s of conditions and in
principle can work with unsimplified conditions (but it may
reject valid program when it can not recognize true condition).
At runtime we have parameters which we can evaluate, so we can
also evaluate conditions. But fact that for specific arguments
condition evaluates to true does not tell you that it will
always evaluate to true. So this is different than simplification.

Unfortunately, this is somewhat intertwined with other parts. If you
look how source travels trough the compiler, first place that is doing
some simplification is handling of Join. It uses a trick to effectively
pass Join to runtime support routines. But we do not want to evaluate
all types during compilation, so this trick replaces actual types in
arguments of categories by symbols. Which means that some important
information is not available during processing of Join.

There is second place which simplifies conditions, this is done at
end of compilation of domains and package. Again, we do not want
to evaluate types there.

Currently some simplifications are done for HyperDoc processing,
as part of generation of libdb (but I would like to remove this
part) and when retrieving information from databases.

> In total, nobody wants that HyperDoc is showing other conditions than
> fricas.github.io/api and the interpreter/compiler yet behaves in another
> way. They should all use the same mechanism, of course.

Exactly.

--
Waldek Hebisch

[Ralf Hemmecke]

Hi Waldek,

> Concerning datastructures, if you (or somebody else) thinks that
> we need different datastructures or some impovement, then I am
> happy to discuss this.

I probably would like to discuss it, but the abbreviated nature of your
macros like Con_form, Cond_rec, etc. and without any documentation make
it hard to browse through the code. That will take time which I anyway
don't have until the end of next week. However, I will then definitely
dive deeper into it.

Ralf

[Grégory Vanuxem]

Hello,

Wow, thanks for this work in this direction. I only discover your code
and just two things now, more later. I am busy actually:

A typo:
constructor_documentation : SY -> String
++ constructor_documentation(n) gives documentation string for
++ constructor with name s. Returns emp[ty string for
^^^
++ undocumented constructors.

And why downcase in BrowserInformation and not lowerCase in String.
Some improvements?

And a last thing, you do not plan to expose BrowserInformation, now,
or you have something else in mind?

Greg

> --
> You received this message because you are subscribed to the Google Groups "FriCAS - computer algebra system" group.
> To unsubscribe from this group and stop receiving emails from it, send an email to fricas-devel...@googlegroups.com.
> To view this discussion visit https://groups.google.com/d/msgid/fricas-devel/aV02PFnzm4F-PJ8w%40fricas.org.

[Waldek Hebisch]

On Tue, Jan 06, 2026 at 07:32:28PM +0100, Grégory Vanuxem wrote:
> Hello,
>
> Wow, thanks for this work in this direction. I only discover your code
> and just two things now, more later. I am busy actually:
>
> A typo:
> constructor_documentation : SY -> String
> ++ constructor_documentation(n) gives documentation string for
> ++ constructor with name s. Returns emp[ty string for
> ^^^
> ++ undocumented constructors.

Thanks.

> And why downcase in BrowserInformation and not lowerCase in String.
> Some improvements?

downcase is lower level, works on whole string and should be faster.
lowerCase from Character has to be called separately for each character
and has more fancy features. And lowerCase in string calls lowerCase
via map, so pays cost of callse. Also, it was easier to write downcase
than to find lowerCase.

> And a last thing, you do not plan to expose BrowserInformation, now,
> or you have something else in mind?

Exposed constructors are supposed to be useful for most users.
I expect that BrowserInformation will be used indirectly.
Normally such constructors are not exposed. Of course, user
who want to use them can expose them.

--
Waldek Hebisch