[c237fe]: doc / html / knowledge_bases / special.html Maximize Restore History

Download this file

special.html    350 lines (334 with data), 16.1 kB

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
<head>
<title>Special</title>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<link rel="stylesheet" href="../stylesheets/pyke.css" type="text/css" />
</head>
<body>
<table id="page-table">
<thead class="head">
<tr id="header1"><th id="header" colspan="3">
&nbsp;
</th></tr>
<tr id="header2">
<th id="crumb-left"></th>
<th id="crumb-line">
<div id="nav">
<ul>
<li><a href="../index.html">Home</a></li>
<li>&gt;</li>
<li><a href="index.html">Knowledge Bases</a></li>
<li>&gt;</li>
<li>Special</li>
</ul>
</div>
</th>
<th id="crumb-right"></th>
</tr>
</thead>
<tbody id="body">
<tr id="body-tr">
<td id="left-nav">
<div id="left-nav-div">
<div class="title-nav"><a href="../index.html">Home</a></div><div class="nav-branch">
<div class="normal-nav"><a href="../about_pyke/index.html">About Pyke</a></div>
<div class="normal-nav"><a href="../logic_programming/index.html">Logic Programming</a></div>
<div class="title-nav"><a href="index.html">Knowledge Bases</a></div><div class="nav-branch">
<div class="normal-nav"><a href="fact_bases.html">Fact Bases</a></div>
<div class="normal-nav"><a href="rule_bases.html">Rule Bases</a></div>
<div class="normal-nav"><a href="question_bases.html">Question Bases</a></div>
<div class="normal-nav"><a href="special.html">Special</a></div>
</div>
<div class="normal-nav"><a href="../pyke_syntax/index.html">Pyke Syntax</a></div>
<div class="normal-nav"><a href="../using_pyke.html">Using Pyke</a></div>
<div class="normal-nav"><a href="../examples.html">Examples</a></div>
<div class="normal-nav"><a href="../PyCon2008-paper.html">PyCon 2008 Paper</a></div>
</div>
</div>
<div id="icons">
<div id="project-page">
<a href="http://sourceforge.net/projects/pyke/">Pyke Project Page</a>
</div>
Please Make a Donation:<br />
<a href="http://sourceforge.net/donate/index.php?group_id=207724">
<img src="http://images.sourceforge.net/images/project-support.jpg"
width="88" height="32" border="0"
alt="Support This Project" /> </a> <br /><br />
Hosted by: <br />
<a href="http://sourceforge.net/projects/pyke">
<img src="http://sflogo.sourceforge.net/sflogo.php?group_id=207724&amp;type=14"
width="150" height="40"
alt="Get Python Knowledge Engine (PyKE) at SourceForge.net. Fast, secure and Free Open Source software downloads" /></a>
</div>
</td>
<td id="main-td">
<div id="main">
<a name="startcontent" id="startcontent"></a>
<div class="document" id="special">
<h1 class="title">Special</h1>
<p>There is only one instance of this 'special' knowledge base, called
<tt class="docutils literal"><span class="pre">special</span></tt>.</p>
<p>The <tt class="docutils literal"><span class="pre">special</span></tt> knowledge base is a collection of miscellaneous helper
<em>knowledge entities</em> that determine whether a statement is true or not in
various interesting ways.</p>
<p>Thus, each entity in this <a class="reference external" href="index.html">knowledge base</a> is a Python function that does
something &quot;special&quot; when run.</p>
<p>The <tt class="docutils literal"><span class="pre">special</span></tt> functions are:</p>
<blockquote>
<ul class="simple">
<li><a class="reference internal" href="#claim-goal">claim_goal</a></li>
<li><a class="reference internal" href="#check-command">check_command</a></li>
<li><a class="reference external" href="special.html#running-commands">command</a></li>
<li><a class="reference internal" href="#general-command">general_command</a></li>
</ul>
</blockquote>
<div class="section" id="claim-goal">
<h2>Claim_goal</h2>
<p>The <tt class="docutils literal"><span class="pre">claim_goal</span></tt> function has no arguments:</p>
<pre class="literal-block">
special.claim_goal()
</pre>
<p>This acts like the <a class="reference external" href="http://en.wikipedia.org/wiki/Prolog">Prolog</a> <a class="reference external" href="http://en.wikipedia.org/wiki/Cut_%28logic_programming%29">cut operator</a>.</p>
<p>In general there are multiple <a class="reference external" href="../logic_programming/rules/index.html">rules</a> that might be used to try to <a class="reference external" href="../using_pyke.html#proving-goals">prove</a> any
<a class="reference external" href="../pyke_syntax/krb_syntax/bc_rule.html#use-clause">goal</a>. They are each tried in the order that they appear in the <a class="reference external" href="../pyke_syntax/krb_syntax/index.html">.krb file</a>.
If one rule fails, the next rule is tried. The goal itself doesn't fail
until all of the rules for it have failed.</p>
<div class="section" id="example">
<h3>Example</h3>
<p>Suppose I want to translate a number, N, into the phrase &quot;N dogs&quot;. I could
use the following rules:</p>
<pre class="literal-block">
one_dog
use n_dogs(1, '1 dog')
n_dogs
use n_dogs($n, $phrase)
when
$phrase = &quot;%d dogs&quot; % $n
</pre>
<p>The problem here is that both rules might be used when <tt class="docutils literal"><span class="pre">n</span></tt> is 1, but the
second rule isn't appropriate in this case. <tt class="docutils literal"><span class="pre">Special.claim_goal()</span></tt> may
be used to fix this, as follows:</p>
<pre class="literal-block">
one_dog
use n_dogs(1, '1 dog')
when
special.claim_goal()
n_dogs
use n_dogs($n, $phrase)
when
$phrase = &quot;%d dogs&quot; % $n
</pre>
<p>The <tt class="docutils literal"><span class="pre">special.claim_goal()</span></tt> prevents the second rule from being used when
<tt class="docutils literal"><span class="pre">n</span></tt> is 1.</p>
</div>
<div class="section" id="explanation">
<h3>Explanation</h3>
<p>When a <a class="reference external" href="../logic_programming/rules/index.html">rule</a> executes <tt class="docutils literal"><span class="pre">special.claim_goal()</span></tt> in its <tt class="docutils literal"><span class="pre">when</span></tt>
clause, none of the rest of the rules will be tried for that <a class="reference external" href="../pyke_syntax/krb_syntax/bc_rule.html#use-clause">goal</a>.
Thus, when <tt class="docutils literal"><span class="pre">special.claim_goal()</span></tt> is <a class="reference external" href="../logic_programming/rules/index.html#backtracking">backtracked</a> over, the goal fails
immediately without trying any more rules for it.</p>
<p>This ends up acting like an &quot;else&quot;. You place it in the <tt class="docutils literal"><span class="pre">when</span></tt> clause
after the <a class="reference external" href="../logic_programming/rules/index.html#premises-and-conclusions">premises</a> that show that this rule <strong>must</strong> be the correct one
to use. Then the subsequent rules will only be tried if these premises
fail, such that <tt class="docutils literal"><span class="pre">special.claim_goal()</span></tt> is never executed.</p>
<p>This means that you don't need to add extra premises in each subsequent rule
to make sure that these premises have <strong>not</strong> occurred.</p>
<p>Without the <tt class="docutils literal"><span class="pre">special.claim_goal()</span></tt> in the prior example, you would have to
write:</p>
<pre class="literal-block">
one_dog
use n_dogs(1, '1 dog')
n_dogs
use n_dogs($n, $phrase)
when
check $n != 1
$phrase = &quot;%d dogs&quot; % $n
</pre>
<p>This is a simple example where it is easy to add the check in the second
rule. But in general, it can be difficult to check for prior conditions,
especially when many rules are involved that each has its own condition.</p>
</div>
</div>
<div class="section" id="running-commands">
<h2>Running Commands</h2>
<p>The remaining three functions deal with running programs (commands) on the
host computer that is running your Pyke program. Their difference is in what
kind of output they provide from the command.</p>
<p>These functions all use the <a class="reference external" href="http://docs.python.org/library/subprocess.html#subprocess.Popen">subprocess.Popen</a> function from the standard
Python library.</p>
<p>Thus, each of these functions accept these three parameters that are passed
on to subprocess.Popen:</p>
<blockquote>
<ul class="simple">
<li>The <tt class="docutils literal"><span class="pre">$command</span></tt> parameter (required).<ul>
<li>This is a tuple indicating the program to run along with its command
line arguments, such as <tt class="docutils literal"><span class="pre">(ls,</span> <span class="pre">'-l')</span></tt>.</li>
</ul>
</li>
<li>The <tt class="docutils literal"><span class="pre">$cwd</span></tt> parameter (optional).<ul>
<li>This specifies the <em>current working directory</em> to run the command in.</li>
<li>If omitted or <tt class="docutils literal"><span class="pre">None</span></tt> the current working directory is not changed.</li>
</ul>
</li>
<li>The <tt class="docutils literal"><span class="pre">$stdin</span></tt> parameter (optional).<ul>
<li>This is a string that is fed to the command as its stdin.<ul>
<li>If the command expects multiple lines of input, this string must
include embedded newlines (e.g., <tt class="docutils literal"><span class="pre">'line</span> <span class="pre">1\nline</span> <span class="pre">2\n'</span></tt>).</li>
</ul>
</li>
<li>If omitted or <tt class="docutils literal"><span class="pre">None</span></tt>, no stdin is provided to the command.</li>
</ul>
</li>
</ul>
</blockquote>
<p>All of these functions fail on <a class="reference external" href="../logic_programming/rules/index.html#backtracking">backtracking</a>.</p>
<div class="section" id="check-command">
<h3>Check_command</h3>
<pre class="literal-block">
special.check_command($command [, $cwd [, $stdin]])
</pre>
<p>Succeeds if the command returns a zero exit status. Fails otherwise. Any
output from the command to stdout or stderr is unavailable.</p>
<blockquote>
<pre class="doctest-block">
&gt;&gt;&gt; from pyke import knowledge_engine
&gt;&gt;&gt; engine = knowledge_engine.engine()
&gt;&gt;&gt; engine.prove_1('special', 'check_command', (('true',),), 0)
((), None)
&gt;&gt;&gt; engine.prove_1('special', 'check_command', (('false',),), 0)
Traceback (most recent call last):
...
pyke.knowledge_engine.CanNotProve: Can not prove special.check_command((false))
</pre>
</blockquote>
</div>
<div class="section" id="command">
<h3>Command</h3>
<pre class="literal-block">
special.command($stdout, $command [, $cwd [, $stdin]])
</pre>
<p>This just looks at the stdout of the command. Any output from the command
to stderr is unavailable.</p>
<p>The <tt class="docutils literal"><span class="pre">$stdout</span></tt> is a tuple of lines with the trailing newlines removed.</p>
<p>This raises <a class="reference external" href="http://docs.python.org/library/subprocess.html#exceptions">subprocess.CalledProcessError</a> if the command returns a non-zero
exit status.</p>
<blockquote>
<pre class="doctest-block">
&gt;&gt;&gt; from __future__ import with_statement
&gt;&gt;&gt; from pyke import pattern, contexts
&gt;&gt;&gt; def run_command(entity, command, cwd=None, stdin=None):
... my_context = contexts.simple_context()
... output = contexts.variable('output')
... with engine.prove('special', entity, my_context,
... (output,
... pattern.pattern_literal(command),
... pattern.pattern_literal(cwd),
... pattern.pattern_literal(stdin))) \
... as gen:
... for no_plan in gen:
... print(output.as_data(my_context))
&gt;&gt;&gt; run_command('command', ('echo', 'hi', 'mom'))
('hi mom',)
&gt;&gt;&gt; run_command('command', ('ls',)) # doctest: +NORMALIZE_WHITESPACE
('ast_syntax', 'cheatsheets', 'examples', 'html', '__init__.py',
'__init__.pyc', 'PyKE.mm', 'r2w.ini', 'source', 'syntax', 'testdocs',
'todo')
&gt;&gt;&gt; run_command('command', ('ls', '-l', 'r2w.ini')) # doctest: +ELLIPSIS
('-rw-r--r-- 1 ... r2w.ini',)
&gt;&gt;&gt; run_command('command', ('tail', '-n', '5', 'template.txt', '-'),
... 'source', # cwd
... 'stdin: line 1\nstdin: line 2\nstdin: line 3\n')
... # doctest: +NORMALIZE_WHITESPACE
('==&gt; template.txt &lt;==',
' } catch(err) {}',
' &lt;/script&gt;',
'&lt;/body&gt;',
'&lt;/html&gt;',
'',
'',
'==&gt; standard input &lt;==',
'stdin: line 1',
'stdin: line 2',
'stdin: line 3')
&gt;&gt;&gt; run_command('command', ('false',))
Traceback (most recent call last):
...
subprocess.CalledProcessError: Command 'false' returned non-zero exit status 1
</pre>
</blockquote>
</div>
<div class="section" id="general-command">
<h3>General_command</h3>
<pre class="literal-block">
special.general_command($output, $command [, $cwd [, $stdin]])
</pre>
<p>This is the fully general form that gives you all output from the command.</p>
<p>The <tt class="docutils literal"><span class="pre">$output</span></tt> is a three tuple: (exit_status, stdout, stderr). Both stdout
and stderr are single strings (with embedded newlines).</p>
<blockquote>
<pre class="doctest-block">
&gt;&gt;&gt; run_command('general_command', ('echo', 'hi', 'mom'))
(0, 'hi mom\n', '')
&gt;&gt;&gt; run_command('general_command', ('cat', 'foobar'))
(1, '', 'cat: foobar: No such file or directory\n')
&gt;&gt;&gt; run_command('general_command', ('tail', '-n', '5', 'r2w.ini', 'foobar'))
... # doctest: +NORMALIZE_WHITESPACE
(1,
&quot;==&gt; r2w.ini &lt;==\ntarget_directory = 'html'\nmacros =
''\n\n[uservalues]\nversion = '0.2'\n&quot;,
&quot;tail: cannot open `foobar' for reading: No such file or directory\n&quot;)
</pre>
</blockquote>
<!-- ADD_LINKS MARKER -->
</div>
</div>
</div>
<!-- <div id="return-to-top">
<a href="#">Return to Top</a>
</div>
-->
</div>
</td>
<td id="right-nav">
<div id="right-nav-div">
<h3>More:</h3>
<div class="right-item"><a href="fact_bases.html">Fact Bases</a><p>Explanation of facts and fact bases.</p>
</div>
<div class="right-item"><a href="rule_bases.html">Rule Bases</a><p>Explanation of rule bases, overview of .krb files and how these files
are compiled and loaded into your Python program.</p>
</div>
<div class="right-item"><a href="question_bases.html">Question Bases</a><p>Explanation of question bases and .kqb files.</p>
</div>
<div class="right-item"><a href="special.html">Special</a><p>Explanation of the <tt class="docutils literal"><span class="pre">special</span></tt> knowledge base.</p>
</div>
</div>
</td>
</tr>
</tbody>
<tfoot id="foot">
<tr id="foot2">
<td id="copyright" colspan="3">
Copyright &copy; 2007-2009 Bruce Frederiksen
</td>
</tr>
</tfoot>
</table>
<div id="last-modified">
Page last modified
Wed, Mar 25 2009.
</div>
<script type="text/javascript">
var gaJsHost = (("https:" == document.location.protocol) ?
"https://ssl." : "http://www.");
document.write(unescape("%3Cscript src='" + gaJsHost +
"google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E"));
</script>
<script type="text/javascript">
try {
var pageTracker = _gat._getTracker("UA-6310805-1");
pageTracker._trackPageview();
} catch(err) {}
</script>
</body>
</html>