Re: pengines extension to html_requires

Hi Anne,

I'm sorry you run into problems, surely partly caused by bad
documentation. We'll certainly do our best to write a better one as
soon as possible.

Maybe we should try to tell a story that most Prolog programmers can
understand? This is how I believe you can think about it in very
simple terms: Suppose you are sitting in front of two computers A and
B, both running a terminal/shell. You can start Prolog in A by
executing swipl in a shell. You can also start Prolog in B by
executing swipl in a shell on that computer. That is akin to running
pengine_create([name('B')]). In a sense, you have created two Prolog
engines, waiting for your next command.

Now you can ask A a query, or start som kind of other process, and
then turn to B and (say) ask another question. You are in control,
since you can choose what to do, and in which Prolog - A or B, guided
by what is printed on the two monitors.

Fortunately, equipped with the pengines library you don't need two
computers or two SWI-Prolog main processes  to program in this way.
You can run pengine_create([name('A')]) and
pengine_create([name('B')]) in the same shell. Better yet, it doesnt
even have to be you doing the programming! Instead, you can write a
program that based on what comes back from A and/or B sends the next
command (or whatever needs to be done).

When writing a web application, you may want to write your
"controller" in JavaScript instead. That's fine, and a perfectly good
way to use Pengines. The commands and handlers that are defined by
pengines.js give you a way to do just that, and to implement JS
widgets that send commands to a Prolog running on a server, in the
Prolog context that it has there (and that you if you own the server
can create yourself) . It can be seen as just an extension of what you
can do in front of a CLI. It also means that Prolog applications
written to be run from a CLI are extremely easy to port to Pengines.
You basically only have to replace calls to write/1 with calls to
pengine_output/1 and calls to read/1 with calls to pengine_input/1.
For your users' experience it may of course mean a lot since you can
choose to repond with JSON and use the JSON to influence the behaviour
of a nice GUI, rather than a behaviour in terms of what is read from
or written to a CLI.

Another way to program with Pengines is to call a goal on B if your
are on A. That's what you do with pengine_rpc/{2,3}. This should be
even easier to grasp than the rest, since you can think of it as a
kind of call/1 that calls its (possibly non-deterministic) goal not
locally but remotely, and in the Prolog context of the remote pengine
server (perhaps also in union with code (if any) that you to sent
along).

pengine_rpc/{2,3} is defined in terms of the other (core) pengine
predicates. That is also kind of nice, I think.

Hope this helps!

And BTW, I would also be interested in knowing if the examples of
interactive programming makes any difference to the ease of
understanding?

- Torbjörn

On Sun, Feb 9, 2014 at 10:18 PM, Anne Ogborn <[email protected]> wrote:
> The real issue isn't options vs no options.
>
> As Jan says-
>
> Note that a small interface has advantages in itself: documentation,
> understanding and reducing the risk of forgetting arguments.
>
> The real issue is that there's no clue which of these are rarely used by the end user,
> or how the commonly used ones fit together. The documentation assumes knowledge of
> concepts that aren't explained. The overview doesn't seem connected to actual use.
>
> After struggling with this apparently more than any other outsider, I'm still stuck
> with a single 'happy path' of slavishly imitating the examples, and not really understanding
> how to go off and fly on my own.



-- 
Torbjörn Lager
Professor of General and Computational Linguistics
Department of Philosophy, Linguistics and Theory of Science
University of Gothenburg
Box 200, SE-405 30 Gothenburg, Sweden
Phone: +46317864962