root/trunk/raw_html/func_wrapping.html

Revision 64, 4.1 kB (checked in by KirkMcDonald, 2 years ago)

PydMain?; build improvements (no more colliding object files); examples and docs updated to use PydMain?

Line 
1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2 <html>
3 <head>
4     <meta http-equiv="Content-Type" content="text/html;charset=iso-8859-1">
5     <link href="pyd.css" rel="stylesheet" type="text/css">
6     <title>Wrapping functions</title>
7 </head>
8
9 <body>
10 %(nav)s
11 <div id="content">
12
13 <h1>Function wrapping</h1>
14
15 <p>Exposing D functions to Python is easy! The heart of Pyd's function wrapping features is the <code>def</code> template function:</p>
16
17 <p><code>void def(alias <span class="t_arg">fn</span>, char[] <span class="t_arg">name</span> = symbolnameof!(fn), <span class="t_arg">fn_t</span> = typeof(&amp;fn), uint <span class="t_arg">MIN_ARGS</span> = minArgs!(fn)) (char[] <span class="arg">docstring</span>="");</code></p>
18     <ul>
19     <li><span class="t_arg">fn</span> is the function to wrap. Note that this is an alias parameter. <code>def</code> is only capable of wrapping full-fledged functions, not function pointers, function literals, or delegates.</li>
20     <li><span class="t_arg">name</span> is the name the function will have inside of Python. Usually, you don't have to specify this. (Special thanks to Don Clugston's Nameof module.)</li>
21     <li><span class="t_arg">fn_t</span> is the function type of the function. Typically, you won't have to specify this. It is used to wrap overloaded functions. (See below.)</li>
22     <li><span class="t_arg">MIN_ARGS</span> is the minimum number of arguments this function can accept. It is used when a function has default arguments. The <code>minArgs</code> template can derive the correct number automatically, so you typically won't specify this manually.</li>
23     <li><span class="arg">docstring</span> is the function's docstring. Note that this is a regular function argument!</li>
24     </ul>
25
26 <p>All calls to <code>def</code> must occur <em>before</em> calling <code>module_init</code>. Any function whose return type and arguments are <a href="conversion.html">convertible</a> can be wrapped by <code>def</code>. <code>def</code> can only wrap functions with <code>in</code> arguments (not <code>out</code> or <code>inout</code> or <code>lazy</code>). <code>def</code> also provides support for wrapping overloaded functions as well as functions with default arguments. Here are some examples:</p>
27
28 <pre class="code"><span class="keyword">import</span> pyd.pyd;
29 <span class="keyword">import</span> std.stdio;
30
31 <span class="keyword">void</span> foo(<span class="keyword">int</span> i) {
32     writefln(<span class="string">"You entered "</span>, i);
33 }
34
35 <span class="keyword">void</span> bar(<span class="keyword">int</span> i) {
36     writefln(<span class="string">"bar: i = "</span>, i);
37 }
38
39 <span class="keyword">void</span> bar(<span class="keyword">char</span>[] s) {
40     writefln(<span class="string">"bar: s = "</span>, s);
41 }
42
43 <span class="keyword">void</span> baz(<span class="keyword">int</span> i=<span class="number">10</span>, <span class="keyword">char</span>[] s=<span class="string">"moo"</span>) {
44     writefln(<span class="string">"i = %%s\ns = %%s"</span>, i, s);
45 }
46
47 <span class="keyword">extern</span> (C) <span class="keyword">void</span> PydMain() {
48     <span class="comment">// Plain old function</span>
49     def!(foo);
50     <span class="comment">// Wraps the lexically first function under the given name</span>
51     def!(bar, <span class="string">"bar1"</span>);
52     <span class="comment">// Wraps the function of the specified type</span>
53     def!(bar, <span class="string">"bar2"</span>, <span class="keyword">void function</span>(<span class="keyword">char</span>[]));
54     <span class="comment">// Wraps the function with default arguments</span>
55     def!(baz);
56
57     module_init();
58 }</pre>
59
60 <p>And when used in Python:</p>
61
62 <pre class="code">&gt;&gt;&gt; import testmodule
63 &gt;&gt;&gt; testmodule.foo(10)
64 You entered 10
65 &gt;&gt;&gt; testmodule.bar1(20)
66 bar: i = 20
67 &gt;&gt;&gt; testmodule.bar2("monkey")
68 bar: s = monkey
69 &gt;&gt;&gt; testmodule.baz()
70 i = 10
71 s = moo
72 &gt;&gt;&gt; testmodule.baz(3)
73 i = 3
74 s = moo
75 &gt;&gt;&gt; testmodule.baz(4, "apple")
76 i = 4
77 s = apple</pre>
78
79 </div>
80
81 </body>
82 </html>
Note: See TracBrowser for help on using the browser.