Changeset 34

Show
Ignore:
Timestamp:
08/10/06 18:22:04 (2 years ago)
Author:
KirkMcDonald
Message:

html_doc: Documented class wrapping, DPyObject

Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved

  • trunk/html_doc/celerid.html

    r33 r34  
    88 
    99<body> 
    10 <div class="nav"><a class="nav" href="index.html">Main</a> | <a class="navcur" href="celerid.html">CeleriD</a> | <a class="nav" href="conversion.html">Type conversion</a> | <a class="nav" href="func_wrapping.html">Function wrapping</a> | <a class="nav" href="class_wrapping.html">Class wrapping</a> | <a class="nav" href="except_wrapping.html">Exception wrapping</a></div> 
     10<div class="nav"><a class="nav" href="index.html">Main</a> | <a class="navcur" href="celerid.html">CeleriD</a> | <a class="nav" href="conversion.html">Type conversion</a> | <a class="nav" href="func_wrapping.html">Function wrapping</a> | <a class="nav" href="class_wrapping.html">Class wrapping</a> | <a class="nav" href="except_wrapping.html">Exception wrapping</a> | <a class="nav" href="dpyobject.html">DPyObject</a></div> 
    1111 
    1212<h1>CeleriD</h1> 

  • trunk/html_doc/class_wrapping.html

    r33 r34  
    88 
    99<body> 
    10 <div class="nav"><a class="nav" href="index.html">Main</a> | <a class="nav" href="celerid.html">CeleriD</a> | <a class="nav" href="conversion.html">Type conversion</a> | <a class="nav" href="func_wrapping.html">Function wrapping</a> | <a class="navcur" href="class_wrapping.html">Class wrapping</a> | <a class="nav" href="except_wrapping.html">Exception wrapping</a></div> 
     10<div class="nav"><a class="nav" href="index.html">Main</a> | <a class="nav" href="celerid.html">CeleriD</a> | <a class="nav" href="conversion.html">Type conversion</a> | <a class="nav" href="func_wrapping.html">Function wrapping</a> | <a class="navcur" href="class_wrapping.html">Class wrapping</a> | <a class="nav" href="except_wrapping.html">Exception wrapping</a> | <a class="nav" href="dpyobject.html">DPyObject</a></div> 
    1111 
    1212<h1>Class wrapping</h1> 
    1313 
    14 <p><i>Coming soon...</i></p> 
     14<p>Exposing D classes to Python is easy! The heart of Pyd's class wrapping features is the <code>wrapped_class</code> template struct:</p> 
     15 
     16<p><code>struct wrapped_class(<span class="t_arg">T</span>, char[] <span class="t_arg">classname</span>);</code></p> 
     17    <ul> 
     18    <li><span class="t_arg">T</span> is the class being wrapped.</li> 
     19    <li><span class="t_arg">classname</span> is the name of the class as it will appear in Python.</li> 
     20    </ul> 
     21 
     22<p>To expose the constructors, methods, and properties of the class, <code>wrapped_class</code> provides a series of template member functions.</p> 
     23 
     24<dl> 
     25<dt><code>static void def(alias <span class="t_arg">fn</span>, char[] <span class="t_arg">name</span>, <span class="t_arg">fn_t</span> = typeof(&amp;fn)) ();</code></dt> 
     26<dd>This wraps a method of the class. It functions exactly like the <code>def</code> function used to <a href="func_wrapping.html">wrap regular functions</a>, with one very important difference: There is no support for default arguments. (This is a side-effect of the fact that you cannot call an alias of a method in D, and delegates do not understand default arguments.)</dd> 
     27 
     28<dt><code>static void prop(alias <span class="t_arg">fn</span>, char[] <span class="t_arg">name</span>, bool <span class="t_arg">RO</span> = false) ();</code></dt> 
     29<dd>This wraps a property. See the examples below for more details. 
     30    <ul> 
     31    <li><span class="t_arg">fn</span> is the name of the property. <code>prop</code> will automatically attempt to wrap both the "get" and "set" forms of the property, unless <span class="t_arg">RO</span> is specified.</li> 
     32    <li><span class="t_arg">name</span> is the name of the property as it will appear in Python.</li> 
     33    <li><span class="t_arg">RO</span> specifies whether this is a <i>read-only</i> property. If true, it will only wrap the "get" form of the property. If false, it will wrap both the "get" and "set" forms. (This is a little hackish, and I will probably try to make this detection more automatic in the future. It also means it cannot support a property that only has a "set" form.)</li> 
     34    </ul> 
     35</dd> 
     36 
     37<dt><code>static void init(<span class="t_arg">C1</span>, <span class="t_arg">C2</span>, <span class="t_arg">C3</span>, ..., <span class="t_arg">C<i>n</i></span>) ();</code></dt> 
     38<dd>This allows you to expose anywhere from zero to 10 of the class's constructors to Python. If the class provides a zero-argument constructor, there is no need to specify it; it is always available. Each of <span class="t_arg">C<i>n</i></span> should be an instance of the <code>pyd.tuples.tuple</code> template (not an instance of the tuple struct <em>itself</em>, but an instance of the <em>template</em>), which in turn supports up to 10 arguments. Each tuple should correspond to a constructor. There is an additional limitation at this time: No two constructors may have the same number of arguments. Pyd will always attempt to call the first constructor with the right number of arguments. If you wish to support a constructor with default arguments, you must specify each possible constructor call as a different template argument to this function. The examples show a few uses of the <code>init</code> function.</dd> 
     39</dl> 
     40 
     41<p>Once you have called all of the member functions of <code>wrapped_class</code> that you wish to, you must issue a call to <code>finalize_class</code>.</p> 
     42 
     43<p><code>void finalize_class(<span class="t_arg">CLS</span>) (<span class="t_arg">CLS</span> <span class="arg">cls</span>);</code></p> 
     44 
     45<p>This does some final initialization of the class and then registers it with Python. Unlike calls to <a href="func_wrapping.html"><code>def</code></a>, calls to <code>finalize_class</code> must occur <em>after</em> calling <code>module_init</code>. The <span class="arg">cls</span> function argument should be an instance of <code>wrapped_class</code>.</p> 
     46 
     47<p>If you ever wish to check whether a given class has been wrapped, Pyd helpfully registers all wrapped classes with the <code>is_wrapped</code> template, which is just a templated <code>bool</code>:</p> 
     48 
     49<p><code>template is_wrapped(<span class="t_arg">T</span>);</code></p> 
     50 
     51<p>If you have a class <code>Foo</code>, you can check whether it is wrapped by simply checking whether <code>is_wrapped!(Foo)</code> is true. It is important to note that this is <em>not</em> a <code>const bool</code>, it is a <em>runtime</em> check.</p> 
     52 
     53<h3>Examples</h3> 
     54 
     55<p>Suppose we have the following simple class:</p> 
     56 
     57<pre class="code"><span class="keyword">import</span> std.stdio; 
     58 
     59<span class="keyword">class</span> Foo { 
     60    <span class="keyword">int</span> m_i; 
     61 
     62    <span class="keyword">this</span>() { m_i = <span class="number">0</span>; } 
     63    <span class="keyword">this</span>(<span class="keyword">int</span> j) { m_i = j; } 
     64 
     65    <span class="keyword">int</span> i() { <span class="keyword">return</span> m_i; } 
     66    <span class="keyword">void</span> i(<span class="keyword">int</span> j) { m_i = j; } 
     67 
     68    <span class="keyword">void</span> foo(<span class="keyword">char</span>[] s) { 
     69        writefln(s, m_i); 
     70    } 
     71}</pre> 
     72 
     73<p>We would expose this class to Python by putting this code in our init function after the call to <code>module_init</code>:</p> 
     74 
     75<pre class="code"><span class="comment">// Make an instance of wrapped_class</span> 
     76wrapped_class!(Foo, <span class="string">"Foo"</span>) f; 
     77<span class="comment">// Wrap the "foo" method</span> 
     78f.def!(Foo.foo, <span class="string">"foo"</span>); 
     79<span class="comment">// Wrap the "i" property</span> 
     80f.prop!(Foo.i, <span class="string">"i"</span>); 
     81<span class="comment">// Wrap the constructor.</span> 
     82f.init!(tuple!(<span class="keyword">int</span>)); 
     83finalize_class(f);</pre> 
     84 
     85<p>Now we can use this type from within Python like any other type.</p> 
     86 
     87<pre class="code">&gt;&gt;&gt; from testmodule import Foo 
     88&gt;&gt;&gt; f = Foo() 
     89&gt;&gt;&gt; f.i 
     900 
     91&gt;&gt;&gt; f.i = 20 
     92&gt;&gt;&gt; f.foo("Hello! i is ") 
     93Hello! i is 20 
     94&gt;&gt;&gt; g = Foo(30) 
     95&gt;&gt;&gt; g.i 
     9630 
     97&gt;&gt;&gt; # We can even subclass our D type 
     98&gt;&gt;&gt; class MyFoo(Foo): 
     99...     def bar(self): 
     100...         print "Hey, i+3 is", self.i + 3 
     101...  
     102&gt;&gt;&gt; h = MyFoo(3) 
     103&gt;&gt;&gt; h.bar() 
     104Hey, i+3 is 6 
     105&gt;&gt;&gt; </pre> 
     106 
    15107</body> 
    16108</html> 

  • trunk/html_doc/conversion.html

    r33 r34  
    88 
    99<body> 
    10 <div class="nav"><a class="nav" href="index.html">Main</a> | <a class="nav" href="celerid.html">CeleriD</a> | <a class="navcur" href="conversion.html">Type conversion</a> | <a class="nav" href="func_wrapping.html">Function wrapping</a> | <a class="nav" href="class_wrapping.html">Class wrapping</a> | <a class="nav" href="except_wrapping.html">Exception wrapping</a></div> 
     10<div class="nav"><a class="nav" href="index.html">Main</a> | <a class="nav" href="celerid.html">CeleriD</a> | <a class="navcur" href="conversion.html">Type conversion</a> | <a class="nav" href="func_wrapping.html">Function wrapping</a> | <a class="nav" href="class_wrapping.html">Class wrapping</a> | <a class="nav" href="except_wrapping.html">Exception wrapping</a> | <a class="nav" href="dpyobject.html">DPyObject</a></div> 
    1111 
    1212<h1>Type conversion</h1> 

  • trunk/html_doc/dpyobject.html

    r33 r34  
    1 <html><head> 
    2     <META http-equiv="content-type" content="text/html; charset=utf-8"> 
    3     <title>pyd.dpyobject</title> 
    4     </head><body> 
    5     <h1>pyd.dpyobject</h1> 
    6     <!-- Generated by Ddoc from pyd\dpyobject.d --> 
    7 <br><br> 
     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>pyd.dpyobject</title> 
     7</head> 
     8 
     9<body> 
     10<div class="nav"><a class="nav" href="index.html">Main</a> | <a class="nav" href="celerid.html">CeleriD</a> | <a class="nav" href="conversion.html">Type conversion</a> | <a class="nav" href="func_wrapping.html">Function wrapping</a> | <a class="nav" href="class_wrapping.html">Class wrapping</a> | <a class="nav" href="except_wrapping.html">Exception wrapping</a> | <a class="navcur" href="dpyobject.html">DPyObject</a></div> 
     11 
     12<h1>pyd.dpyobject</h1> 
     13<!-- Generated by Ddoc from pyd\dpyobject.d --> 
     14<p>The DPyObject class wraps a PyObject*, using the D garbage collector to handle the reference count so that you don't have to. It also overloads quite a lot of operators, and tries to make using Python objects in D code as much like using them in Python as possible. However, it is incomplete (the function and method call methods in particular need work, and there are a number of helper functions that need to be written), and remains a work in progress.</p> 
     15 
    816<dl><dt><big>class <u>DPyObject</u>; 
    917</big></dt> 
    …… 
    1523<br><br> 
    1624<b>Authors:</b><br> 
    17 <a href="mailto:kirklin.mcdonald@gmail.com">Kirk McDonald</a> 
    18 <br><br> 
    19 <b>Date:</b><br> 
    20 June 18, 2006 
     25Kirk McDonald 
    2126<br><br> 
    2227<b>See Also:</b><br> 
    …… 
    3035<br><br> 
    3136<b>Params:</b><br> 
    32 <table><tr><td>PyObject * <i>o</i></td> 
    33 <td>The PyObject to wrap.</td></tr> 
    34 <tr><td>bool <i>borrowed</i></td> 
    35 <td>Whether <i>o</i> is a borrowed reference. Instances 
     37<table> 
     38<tr><td>PyObject * <i>o</i></td>  <td>The PyObject to wrap.</td></tr> 
     39<tr><td>bool <i>borrowed</i></td> <td>Whether <i>o</i> is a borrowed reference. Instances 
    3640                 of DPyObject always own their references. 
    3741                 Therefore, Py_INCREF will be called if <i>borrowed</i> is 
    38                  <font color=blue><b>true</b></font>.</td></tr> 
    39 </table><br> 
    40  
    41 </dd> 
    42 <dt><big>this(); 
    43 </big></dt> 
    44 <dd>The default constructor constructs an instance of the Py_None DPyObject. 
    45 <br><br> 
    46  
    47 </dd> 
    48 <dt><big>PyObject * <u>ptr</u>(); 
    49 </big></dt> 
    50 <dd>Returns a borrowed reference to the PyObject. 
    51       
    52 <br><br> 
    53  
    54 </dd> 
    55 <dt><big>bool <u>hasattr</u>(char[] <i>attr_name</i>); 
     42                 true.</td></tr> 
     43</table><br /></dd> 
     44 
     45<dt><big>this();</big></dt> 
     46<dd>The default constructor constructs an instance of the Py_None DPyObject.<br /><br /></dd> 
     47 
     48<dt><big>PyObject * <u>ptr</u>();</big></dt> 
     49<dd>Returns a borrowed reference to the PyObject.<br><br></dd> 
     50 
     51<dt><big>bool <u>hasattr</u>(char[] <i>attr_name</i>);</big></dt> 
     52<dd>Same as hasattr(this, <i>attr_name</i>) in Python.<br><br></dd> 
     53 
     54<dt><big>bool <u>hasattr</u>(DPyObject <i>attr_name</i>); 
    5655</big></dt> 
    5756<dd>Same as hasattr(this, <i>attr_name</i>) in Python. 
    …… 
    5958 
    6059</dd> 
    61 <dt><big>bool <u>hasattr</u>(DPyObject <i>attr_name</i>); 
    62 </big></dt> 
    63 <dd>Same as hasattr(this, <i>attr_name</i>) in Python. 
    64 <br><br> 
    65  
    66 </dd> 
    6760<dt><big>DPyObject <u>getattr</u>(char[] <i>attr_name</i>); 
    6861</big></dt> 
    …… 
    161154 
    162155</dd> 
    163 <dt><big>DPyObject <u>opCall</u>(DPyObject <i>args</i> = cast(DPyObject)null); 
    164 </big></dt> 
    165 <dd>Calls the DPyObject. 
     156<dt><big>DPyObject <u>opCall</u>(DPyObject <i>args</i> = null); 
     157</big></dt> 
     158<dd>Calls the DPyObject. <strong>(Note: The opCall functions will be changing in the future to something more useful.)</strong> 
    166159<br><br> 
    167160<b>Params:</b><br> 
    …… 
    193186 
    194187</dd> 
    195 <dt><big>DPyObject <u>method</u>(char[] <i>name</i>, DPyObject <i>args</i> = cast(DPyObject)null); 
     188<dt><big>DPyObject <u>method</u>(char[] <i>name</i>, DPyObject <i>args</i> = null); 
    196189</big></dt> 
    197190<dd><br><br> 
    …… 
    398391<dd><br><br> 
    399392</dd> 
    400 <dt><big>DPyObject <u>pow</u>(DPyObject <i>o1</i>, DPyObject <i>o2</i> = cast(DPyObject)null); 
     393<dt><big>DPyObject <u>pow</u>(DPyObject <i>o1</i>, DPyObject <i>o2</i> = null); 
    401394</big></dt> 
    402395<dd><br><br> 
    …… 
    468461<dd><br><br> 
    469462</dd> 
    470 <dt><big>DPyObject <u>powAssign</u>(DPyObject <i>o1</i>, DPyObject <i>o2</i> = cast(DPyObject)null); 
     463<dt><big>DPyObject <u>powAssign</u>(DPyObject <i>o1</i>, DPyObject <i>o2</i> = null); 
    471464</big></dt> 
    472465<dd><br><br> 
    …… 
    592585</dl> 
    593586 
    594     <hr><small>Page generated by <a href="http://www.digitalmars.com/d/ddoc.html">Ddoc</a>. </small> 
    595     </body></html> 
     587<hr /> 
     588<small>Page generated by <a href="http://www.digitalmars.com/d/ddoc.html">Ddoc</a>.</small> 
     589</body> 
     590</html> 

  • trunk/html_doc/except_wrapping.html

    r33 r34  
    88 
    99<body> 
    10 <div class="nav"><a class="nav" href="index.html">Main</a> | <a class="nav" href="celerid.html">CeleriD</a> | <a class="nav" href="conversion.html">Type conversion</a> | <a class="nav" href="func_wrapping.html">Function wrapping</a> | <a class="nav" href="class_wrapping.html">Class wrapping</a> | <a class="navcur" href="except_wrapping.html">Exception wrapping</a></div> 
     10<div class="nav"><a class="nav" href="index.html">Main</a> | <a class="nav" href="celerid.html">CeleriD</a> | <a class="nav" href="conversion.html">Type conversion</a> | <a class="nav" href="func_wrapping.html">Function wrapping</a> | <a class="nav" href="class_wrapping.html">Class wrapping</a> | <a class="navcur" href="except_wrapping.html">Exception wrapping</a> | <a class="nav" href="dpyobject.html">DPyObject</a></div> 
    1111 
    1212<h1>Exception wrapping</h1> 

  • trunk/html_doc/func_wrapping.html

    r33 r34  
    88 
    99<body> 
    10 <div class="nav"><a class="nav" href="index.html">Main</a> | <a class="nav" href="celerid.html">CeleriD</a> | <a class="nav" href="conversion.html">Type conversion</a> | <a class="navcur" href="func_wrapping.html">Function wrapping</a> | <a class="nav" href="class_wrapping.html">Class wrapping</a> | <a class="nav" href="except_wrapping.html">Exception wrapping</a></div> 
     10<div class="nav"><a class="nav" href="index.html">Main</a> | <a class="nav" href="celerid.html">CeleriD</a> | <a class="nav" href="conversion.html">Type conversion</a> | <a class="navcur" href="func_wrapping.html">Function wrapping</a> | <a class="nav" href="class_wrapping.html">Class wrapping</a> | <a class="nav" href="except_wrapping.html">Exception wrapping</a> | <a class="nav" href="dpyobject.html">DPyObject</a></div> 
    1111 
    1212<h1>Function wrapping</h1> 
    …… 
    2222    </ul> 
    2323 
    24 <p>Any function whose return type and arguments are <a href="conversion.html">convertable</a> can be wrapped by <code>def</code>. <code>def</code> also provides support for wrapping overloaded functions as well as functions with default arguments. Here are some examples:</p> 
     24<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">convertable</a> can be wrapped by <code>def</code>. <code>def</code> also provides support for wrapping overloaded functions as well as functions with default arguments. Here are some examples:</p> 
    2525 
    2626<pre class="code"><span class="keyword">import</span> pyd.pyd; 

  • trunk/html_doc/index.html

    r33 r34  
    88 
    99<body> 
    10 <div class="nav"><a class="navcur" href="index.html">Main</a> | <a class="nav" href="celerid.html">CeleriD</a> | <a class="nav" href="conversion.html">Type conversion</a> | <a class="nav" href="func_wrapping.html">Function wrapping</a> | <a class="nav" href="class_wrapping.html">Class wrapping</a> | <a class="nav" href="except_wrapping.html">Exception wrapping</a></div> 
     10<div class="nav"><a class="navcur" href="index.html">Main</a> | <a class="nav" href="celerid.html">CeleriD</a> | <a class="nav" href="conversion.html">Type conversion</a> | <a class="nav" href="func_wrapping.html">Function wrapping</a> | <a class="nav" href="class_wrapping.html">Class wrapping</a> | <a class="nav" href="except_wrapping.html">Exception wrapping</a> | <a class="nav" href="dpyobject.html">DPyObject</a></div> 
    1111 
    1212<h1>Pyd</h1> 

  • trunk/infrastructure/build_wiki_ddoc.bat

    r33 r34  
    1 C:\dmd\dmd\bin\dmd.exe -o- -Ddpyd\wiki_doc pyd\class_wrap.d pyd\ctor_wrap.d pyd\def.d pyd\dg_convert.d pyd\exception.d pyd\ftype.d pyd\make_object.d pyd\dpyobject.d pyd\pyd.d -Ipython\headers 
     1C:\dmd\dmd\bin\dmd.exe -o- -Ddpyd\wiki_doc pyd\class_wrap.d pyd\ctor_wrap.d pyd\def.d pyd\dg_convert.d pyd\dpyobject.d pyd\exception.d pyd\ftype.d pyd\make_object.d pyd\op_wrap.d pyd\pyd.d pyd\tuples.d -Ipython\headers 
    22 
    33pause 

  • trunk/infrastructure/pyd/wiki_doc/wiki_doc/wikidoc.ddoc

    r24 r34  
    1 DDOC = <h1>$(TITLE)</h1> 
     1DDOC = <!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>$(TITLE)</title> 
     7</head> 
     8 
     9<body> 
     10<div class="nav"><a class="nav" href="index.html">Main</a> | <a class="nav" href="celerid.html">CeleriD</a> | <a class="nav" href="conversion.html">Type conversion</a> | <a class="nav" href="func_wrapping.html">Function wrapping</a> | <a class="nav" href="class_wrapping.html">Class wrapping</a> | <a class="nav" href="except_wrapping.html">Exception wrapping</a></div> 
     11 
     12<h1>$(TITLE)</h1> 
     13 
    214$(BODY) 
     15</body> 
     16</html> 
     17 
     18