Improving documentation and discoverability

[dwwmmn]

Hi all. I am relatively inexperienced with Prolog and completely new to Scryer. This was my first interaction with the REPL:

➜ scryer-prolog
?- open("test.txt", w, Stream), write(Stream, test(term)), close(Stream).
caught: error(domain_error(source_sink,"test.txt"),open/4)
?- open("test.txt", write, Stream), write(Stream, test(term)), close(Stream).
caught: error(domain_error(source_sink,"test.txt"),open/4)
?- open("/home/user/test.txt", write, Stream), write(Stream, test(term)), close(Stream).
caught: error(domain_error(source_sink,"/home/user/test.txt"),open/4)
?- apropos(open).
caught: error(existence_error(procedure,apropos/1),apropos/1)
?- help(open).
caught: error(existence_error(procedure,help/1),help/1)
?- man(open).
caught: error(existence_error(procedure,man/1),man/1)
?- listing(open).
caught: error(existence_error(procedure,listing/1),listing/1)
?- listings(open).
caught: error(existence_error(procedure,listings/1),listings/1)
?- errno(procedure).
caught: error(existence_error(procedure,errno/1),errno/1)
?- help.
caught: error(existence_error(procedure,help/0),help/0)
?- man.
caught: error(existence_error(procedure,man/0),man/0)
?-

... It went on like that for a while, but I think you get the picture. Eventually I went directly to the definition of open/4 in src/lib/builtins.pl and even that didn't quite help, as there are no comments. The wiki is blank, and I didn't see a link to online documentation in the README.

Contrast this with systems like SWI-Prolog:

Now, I'm aware my inexperience is mostly to blame for this, but I think more descriptive error messages and the ability to view documentation in the REPL would go a long way towards making the system friendlier. error(domain_error(source_sink, "test.txt"), open/4) is compliant with the ISO standard, but presents information in a format unfamiliar to programmers from other languages.

I was going to make this an issue, but after reading more about Scryer, I see that the system is still under heavy development. I realize the main contributors may not want to start writing documentation which could change or even be completely reworked in future releases. And, maybe these error messages are perfectly readable to everyone else and it's just me :)

What do others think? Would a help/1 or similar be a worthwhile endeavor at this stage? If so, I'd be willing to contribute a PR or two.

[triska]

Which version of Scryer Prolog are you using? Specifically, as of 5a3ee3a, using strings for file names should work (see #566). With the latest development version, I get:

?- open("test.txt", w, Stream).
caught: error(domain_error(io_mode,w),open/4)

This makes quite clear that w is the problem in the sample query.

In addition, I second what @aarroyoc wrote: It is best to use the predicates from library(pio) for input and output! In this way, you do not need to open and close files explicitly yourself, the library will do it for you, and also in such a way that it does not leak resources even in case of errors (for example, "forgetting" to close a file handle if an error occurs).

[dwwmmn]

I was using cargo:0.8.127 which appears to be the most updated version from crates.io. Downloading the repository from git and building with cargo build, the sample query open("test.txt", write, Stream) runs as expected. cargo run -- --version gives me v0.8.123-639-gca62e54. So, one problem solved.

Thank you as well for the tip about library(pio), I will have to learn how to use it.

To maybe rephrase my question a bit better: When running the original query, we get the error caught: error(domain_error(io_mode,w),open/4). If I understand correctly, this says that w is not in the domain of acceptable values for the second argument of open/3, which specifies the I/O mode. Ok, all well and good. But what is the domain of acceptable values, and what is the best way for me to discover that domain so I can use the predicate correctly?

[aarroyoc]

I agree the docs need to improve a lot. Because right now they're non-existent. It's also true that Scryer tries to be ISO compliant so any ISO compliant docs (books, tutorials,...) will mostly work. But I think we need to develop a tool to write the docs near the predicate definitions. SWI uses PlDoc, which allows them to have their docs online with hyperlinks and search and all that stuff. And also that tool can be used to generate the content of the help/1 predicate. Probably a good place to use Prolog meta capabilities!

On the errors, I don't know how to approach them. What you're getting are the ISO standard exceptions. You can catch them in your code and they will be the same and you can unify against the error. Right now the REPL (which is just Prolog) just catches everything and prints it. Take into account that the same system works for your exceptions. We could add more information for some common exceptions but I think it won't be enough. We can't derive more helpful information from the Prolog exception. We would need custom Rust code to track that information. And that would only work the predicates that are "magic" and are implemented in Rust. A bit tricky in my opinion. And all in all, exceptions are not that common in pure Prolog code (open is not pure, because I/O). And even if you want to do I/O we recommend using the library pio which uses DCGs for reading and writing.

[pmoura]

I agree the docs need to improve a lot. Because right now they're non-existent. It's also true that Scryer tries to be ISO compliant so any ISO compliant docs (books, tutorials,...) will mostly work. But I think we need to develop a tool to write the docs near the predicate definitions. SWI uses PlDoc, which allows them to have their docs online with hyperlinks and search and all that stuff. And also that tool can be used to generate the content of the help/1 predicate. Probably a good place to use Prolog meta capabilities!

The key for a comprehensive set of developer tools is a comprehensive reflection API. The ISO Prolog standards specifies only current_predicate/1 and predicate_property/2 (well, clause/2 can also be seen as a reflection predicate). But much more is required. E.g. being able to find which files are loaded and their properties. In the case of Logtalk, I implemented a portable reflection API that supports its developer tools, which are (with the exception of the linter and make tools that are integrated with the compiler/runtime) regular applications (meaning that users can more easily contribute to them or even replace them with their own versions).

In the particular case of documentation tools, Logtalk's lgtdoc uses the source data collected when source files are compiled and made available by the reflection API. Users can add additional entity and predicate information using documentation directives (an approach common to some Prolog systems like Ciao and ECLiPSe). The tool then allows exporting documentation is several formats, including Sphinx, which provides search capabilities.

Scryer Prolog could use a similar approach (of course, Scryer users running Logtalk can already use all the tools I referenced).