<!DOCTYPE html>
<html lang="en">
    <head>
        <meta http-equiv="content-type" content="text/html; charset=UTF-8">
        <meta charset="utf-8">
        <title>Pengines</title>
        <meta name="viewport" content="width=device-width, initial-scale=1.0">
        <meta name="description" content="">
        <meta name="author" content="">
        <!-- Bootstrap core CSS -->
        <link href="../vendor/bootstrap/css/bootstrap.min.css" rel="stylesheet">
        <!-- Documentation extras -->
        <link href="manual_files/docs.css" rel="stylesheet">
        <!-- Le HTML5 shim, for IE6-8 support of HTML5 elements -->
        <!--[if lt IE 9]>
        <script src="assets/js/html5shiv.js"></script>
        <![endif]-->
        <!-- Le fav and touch icons -->
        <link rel="apple-touch-icon-precomposed" sizes="144x144" href="http://twitter.github.io/bootstrap/assets/ico/apple-touch-icon-144-precomposed.png">
        <link rel="apple-touch-icon-precomposed" sizes="114x114" href="http://twitter.github.io/bootstrap/assets/ico/apple-touch-icon-114-precomposed.png">
        <link rel="apple-touch-icon-precomposed" sizes="72x72" href="http://twitter.github.io/bootstrap/assets/ico/apple-touch-icon-72-precomposed.png">
        <link rel="apple-touch-icon-precomposed" href="http://twitter.github.io/bootstrap/assets/ico/apple-touch-icon-57-precomposed.png">
        <link rel="shortcut icon" href="http://twitter.github.io/bootstrap/assets/ico/favicon.png">
        <style>
            li.L0, li.L1, li.L2, li.L3,
            li.L5, li.L6, li.L7, li.L8
            { list-style-type: decimal !important }
            label {
                font-weight: bold;
            }
            code {
                color: black;
            }
            dd {
                margin-left: 30px;
            }
        </style>
        <style id="holderjs-style" type="text/css">.holderjs-fluid {font-size:16px;font-weight:bold;text-align:center;font-family:sans-serif;margin:0}</style>
    </head>
    <body data-twttr-rendered="true" data-spy="scroll" data-target=".bs-docs-sidebar">
        <header class="navbar navbar-inverse navbar-fixed-top bs-docs-nav">
            <div class="container">
                <div class="navbar-header">
                  <button class="navbar-toggle" type="button" data-toggle="collapse" data-target=".bs-navbar-collapse">
                    <span class="icon-bar"></span>
                    <span class="icon-bar"></span>
                    <span class="icon-bar"></span>
                  </button>
                    <a href="/docs/index.html" class="navbar-brand">Pengines</a>
                </div>
                <nav class="collapse navbar-collapse bs-navbar-collapse">
                    <ul class="nav navbar-nav">
                        <li>
                            <a href="/docs/getting_started.html">Getting started</a>
                        </li>
                        <li>
                            <a href="/apps/scratchpad/index.html">Scratchpad</a>
                        </li>
                        <li>
                            <a href="/apps/swish/index.html">SWISH</a>
                        </li>
                        <li class="active">
                            <a href="/docs/documentation.html">Docs</a>
                        </li>
                        <li>
                            <a href="/admin/statistics.html">Stats</a>
                        </li>
                        <li>
                            <a href="/admin/server">Admin</a>
                        </li>
                    </ul>
                </nav>
            </div>
        </header>
        <div class="bs-header" id="content">
            <div class="container">
                <h1>Documentation</h1>
                <p>Here we document Pengines' JavaScript and Prolog APIs. </p>
            </div>
        </div>
        <div class="container bs-docs-container">
            <div class="row">
                <div class="col-md-3">
                    <div class="bs-sidebar hidden-print affix-top">
                        <ul class="nav bs-sidenav">
                            <li><a href="#javascript-api">The JavaScript API</a></li>
                            <li><a href="#prolog-preds">The Prolog API</a></li>
                            <li><a href="#more-prolog-docs">More Prolog documentation</a></li>
                        </ul>
                    </div>
                </div>
                <div class="col-md-9">

                    <!-- API overview
                        ================================================== -->
                    <div class="bs-docs-section">
                        <div class="page-header">
                            <h1 id="javascript-api">The JavaScript API</h1>
                        </div>
                        <p>The Pengines JavaScript API allows a web application developer to create a pengine object like so:</p>
                        <pre>
var pengine = new Pengine(<em>options</em>);</pre>
                        <p><em>options</em> is a JavaScript object contaning zero or more of</p>
                        <dl>
                            <dt><code>server:<em>string</em></code></dt>
                            <dd>A URL pointing to the Pengines server on which to create the pengine. Default is the server from which pengines.js is loaded.</dd>
                            <dt><code>application:<em>string</em></code></dt>
                            <dd>The name of the application in which the pengine is to be run. Default is "pengine_sandbox".</dd>
                            <dt><code>ask:<em>string</em></code></dt>
                            <dd>The query passed to the pengine immediately after its creation. By default no query is passed. Using this option will typically save one network roundtrip and thus using it with a deterministic query will result in just one roundtrip being made.</dd>
                            <dt><code>template:<em>string</em></code></dt>
                            <dd>A Prolog variable (or a term containing Prolog variables) shared with the query. Meaningful only if the ask option is specified. By default the value of this option is the variable bindings of the query passed in the ask option (a list of Name=Var pairs). Variable names in the query starting with an underscore character will however not appear in the list.</dd>
                            <dt><code>chunk:<em>integer</em></code></dt>
                            <dd>The maximum number of solutions to retrieve in one chunk. 1 means no chunking (default).</dd>
                            <dt><code>destroy:<em>boolean</em></code></dt>
                            <dd>Determines if the pengine is to destroy itself after having run a query to completion. Defaults to <code>true</code>.</dd>
                            <dt><code>src_text:<em>string</em></code></dt>
                            <dd>Prolog source code to be injected in the pengine before attempting to solve any queries.</dd>
                            <dt><code>src_url:<em>string</em></code></dt>
                            <dd>A URL resolving to a file containing Prolog source code to be injected in the pengine before attempting to solve any queries.</dd>
                            <dt><code>format:<em>string</em></code></dt>
                            <dd>Determines the format of event responses. Format is a string, either <code>json</code> (default), <code>json-s</code> or <code>json-html</code>. In addition, new formats can be added by defining <code>event_to_json/3</code>. See <code>library(pengines_io)</code>. </dd>
                            <dt><code>oncreate:<em>function</em></code></dt>
                            <dd>JavaScript function to be called when a pengine has been created. The expression <code>this.id</code> in the scope of the function points to the id of the pengine.</dd>
                            <dt><code>onsuccess:<em>function</em></code></dt>
                            <dd>Called when the pengine responds with a successful answer to a query. In the scope of the function the expression <code>this.data</code> points to a <em>list</em> of objects each representing a solution to the query, <code>this.more</code> evaluates to a boolean indicating whether more solutions may exist, and<code>this.id</code> points to the id of the pengine returning the answer.</dd>
                            <dt><code>onfailure:<em>function</em></code></dt>
                            <dd>Called when the pengine fails to find a solution. The expression <code>this.id</code> points to the id of the pengine reporting the failure.</dd>
                            <dt><code>onerror:<em>function</em></code></dt>
                            <dd>Called when the pengine throws an error. The expression <code>this.data</code> in the scope of the function evaluates to an error message in the form of a string. The expression <code>this.id</code> points to the id of the pengine returning the error.</dd>
                            <dt><code>onprompt:<em>function</em></code></dt>
                            <dd>Called when the pengine evaluates the <code>pengine_input/2</code> predicate. The expression <code>this.data</code> in the scope of the function evaluates to a prompt in the form of a string or a JavaScript object. The expression <code>this.id</code> points to the id of the pengine producing the prompt.</dd>
                            <dt><code>onoutput:<em>function</em></code></dt>
                            <dd>Called when the pengine has evaluated the built in <code>pengine_output/1</code> predicate. The expression <code>this.data</code> in the scope of the function evaluates to a string or a JavaScript object. The expression <code>this.id</code> points to the id of the pengine generating the output.</dd>
                            <dt><code>onstop:<em>function</em></code></dt>
                            <dd>Called when a running query has been successfully stopped. The expression <code>this.id</code> points to the id of the pengine having been stopped.</dd>
                            <dt><code>onabort:<em>function</em></code></dt>
                            <dd>Called when a running query has been successfully aborted. The expression <code>this.id</code> points to the id of the pengine having been aborted.</dd>
                            <dt><code>ondestroy:<em>function</em></code></dt>
                            <dd>Called when the pengine has been successfully destroyed. The expression <code>this.id</code> points to the id of the pengine having been destroyed.</dd>
                        </dl>
                        <p>A pengine object also provides access to the following fields and methods.</p>
                        <dl>
                            <dt><code>pengine.id</code></dt>
                            <dd>Evaluates to the id of the pengine (a string). Note that the pengine must have been created before this field will have a non-null value, i.e. the oncreate handler must have been called.</dd>
                            <dt><code>pengine.ask(<em>query</em>, <em>options</em>)</code></dt>
                            <dd>Runs <em>query</em> in search for the first solution. Throws an error if the query is syntactically or semantically malformed or if running it could compromise the safety of the server. <em>options</em> is a JavaScript object contaning zero or more of<br /><br />
                            <dl>
                                <dt><code>template: <em>string</em></code></dt>
                                <dd>A Prolog variable (or a term containing Prolog variables) shared with the query. Meaningful only if the ask option is specified. By default the value of this option is the variable bindings of the query passed in the ask option (a list of Name=Var pairs). Variable names in the query starting with an underscore character will however not appear in the list.</dd>
                                <dt><code>chunk: <em>integer</em></code></dt>
                                <dd>The maximum number of solutions to retrieve in one chunk. 1 means no chunking (default).</dd>
                            </dl>
                            </dd>
                            <dt><code>pengine.next()</code></dt>
                            <dd>Triggers a search for the next solution.</dd>
                            <dt><code>pengine.stop()</code></dt>
                            <dd>Stops searching for solutions. Terminates the running query gracefully.</dd>
                            <dt><code>pengine.respond(<em>string</em> or <em>object</em>)</code></dt>
                            <dd>Inputs a term in response to a prompt from an invocation of <code>pengine_input/2</code> that is now waiting to receive data from the outside. Throws an error if <em>string</em> cannot be parsed as a Prolog term or if <em>object</em> cannot be serialised into JSON.</dd>
                            <dt><code>pengine.abort()</code></dt>
                            <dd>Terminates the running query by force.</dd>
                            <dt><code>pengine.destroy()</code></dt>
                            <dd>Destroys the pengine.</dd>
                        </dl>

                    </div>

                    <!-- API overview
                        ================================================== -->
                    <div class="bs-docs-section">
                        <div class="page-header">
                            <h1 id="prolog-preds">The Prolog API</h1>
                        </div>
                        <p>The Prolog API is documented in the following document:
                            <a href="http://www.swi-prolog.org/pldoc/man?section=pengine-libs">Prolog API</a>
                        </p>
                    </div>

                    <!-- API overview
                        ================================================== -->
                    <div class="bs-docs-section">
                        <div class="page-header">
                            <h1 id="more-prolog-docs">More Prolog documentation</h1>
                        </div>
                        <ul>
                            <li><a href="http://www.swi-prolog.org/pldoc/doc_for?object=manual" target="_newtab">SWI-Prolog documentation</a></li>
                        </ul>
                </div>
            </div>
        </div>
        <br />
        <br />

        <!-- Footer
            ================================================== -->
        <footer class="footer">
            <div class="container">
            </div>
        </footer>
        <!-- Placed at the end of the document so the pages load faster -->
        <script src="../vendor/jquery/jquery-2.0.3.min.js"></script>
        <script src="../vendor/bootstrap/js/bootstrap.min.js"></script>
        <script src="manual_files/widgets.js"></script>
        <script src="manual_files/holder.js"></script>
        <script src="manual_files/application.js"></script>
    </body>
</html>
