aboutsummaryrefslogtreecommitdiff
path: root/src
diff options
context:
space:
mode:
authorMartin Peach <mrpeach@users.sourceforge.net>2011-10-05 21:23:18 +0000
committerIOhannes m zmölnig <zmoelnig@iem.at>2015-10-14 14:28:31 +0200
commit7d3cb69c05bb79d7e8f7176521d325e1112bfb28 (patch)
tree8670deff622b33628b12a4cca2329a35956ca772 /src
parent80054545c8c941bfc3df640090b148f044e272e6 (diff)
Added a pdlua_HOWTO subpatch based on lua.txt
svn path=/trunk/externals/loaders/pdlua/; revision=15523
Diffstat (limited to 'src')
-rw-r--r--src/pdlua-help.pd228
1 files changed, 213 insertions, 15 deletions
diff --git a/src/pdlua-help.pd b/src/pdlua-help.pd
index efd122d..53a83a2 100644
--- a/src/pdlua-help.pd
+++ b/src/pdlua-help.pd
@@ -1,15 +1,213 @@
-#N canvas 0 22 534 259 10;
-#X msg 44 58;
-#X text 118 58 << more methods will come (maybe);
-#X text 118 102 << global interface to pdlua;
-#X text 118 20 << load and run a Lua file (searches Pd's path);
-#X msg 17 21 load hello.lua;
-#X text 17 191 See also:;
-#X obj 37 216 hello;
-#X text 15 135 Side-effects:;
-#X obj 17 101 pdlua;
-#X obj 87 216 pdluax hello;
-#X text 29 157 [pdlua] registers a loader that allows Pd classes written
-in Lua to be loaded.;
-#X connect 0 0 8 0;
-#X connect 4 0 8 0;
+#N canvas 626 402 534 259 10;
+#X declare -stdpath doc/examples/pdlua;
+#X msg 44 58;
+#X text 70 57 << more methods will come (maybe);
+#X text 53 99 << global interface to pdlua;
+#X text 113 20 << load and run a Lua file (searches Pd's path);
+#X msg 17 21 load hello.lua;
+#X text 17 191 See also:;
+#X obj 37 216 hello;
+#X text 15 135 Side-effects:;
+#X obj 17 101 pdlua;
+#X obj 87 216 pdluax hello;
+#X text 29 157 [pdlua] registers a loader that allows Pd classes written
+in Lua to be loaded.;
+#X obj 282 108 declare -stdpath doc/examples/pdlua;
+#N canvas 14 464 573 837 pdlua_HOWTO 0;
+#X obj 13 3 cnv 15 400 140 empty empty pdlua_HOWTO 20 12 0 14 -135137
+-66577 0;
+#X obj 13 144 cnv 15 400 160 empty empty Class_Creation 20 12 0 14
+-203904 -66577 0;
+#X obj 13 305 cnv 15 400 300 empty empty Object_Initialization 20 12
+0 14 -261234 -66577 0;
+#X obj 13 606 cnv 15 400 120 empty empty empty 20 12 0 14 -135137 -66577
+0;
+#X obj 13 727 cnv 15 400 170 empty empty empty 20 12 0 14 -203904 -66577
+0;
+#X obj 13 1601 cnv 15 400 100 empty empty Sending_To_Receivers 20 12
+0 14 -261234 -66577 0;
+#X obj 13 1702 cnv 15 400 120 empty empty Receivers 20 12 0 14 -135137
+-66577 0;
+#X text 31 28 The Lua loader included in -lib pdlua allows externals
+for Pd to be written in the Lua programming language. (http://www.lua.org/)
+;
+#X text 31 70 If you try to create an object [foo] in Pd \, Pd checks
+if the class "foo" exists. If it doesn't \, it tries to load an external
+file that "probably" will contain code for "foo". The Lua loader adds
+support for loading "foo.pd_lua" when you try to create [foo].;
+#X obj 13 898 cnv 15 400 70 empty empty Object_Finalization 20 12 0
+14 -261234 -66577 0;
+#X text 31 216 This creates a new Pd class called "foo". The 'local'
+declaration is optional \, but recommended -- without it \, 'foo' is
+global \, which means any Lua code can modify it (possibly by accident).
+;
+#X text 31 164 The first expression/statement in the text file "foo.pd_lua"
+should be of the form:;
+#X obj 13 969 cnv 15 400 400 empty empty Inlet_Methods 20 12 0 14 -135137
+-66577 0;
+#X text 31 418 or equivalently:;
+#X obj 13 1370 cnv 15 400 230 empty empty Sending_To_Outlets 20 12
+0 14 -203904 -66577 0;
+#X text 31 326 Then you can add methods to the Pd class. The most important
+one is 'initialize' \, which is executed when a new object is created:
+;
+#X text 47 514 [foo a b 1 2 3 c];
+#X text 31 485 'sel' is usually (always?) the class name \, 'atoms'
+are the creation arguments in a Lua table. For example a Pd object
+;
+#X text 32 532 would have sel equal to "foo" and the atoms:;
+#X text 31 605 Being a method \, 'initialize' has a 'self' variable
+(which is the object to be created) \, and if you want your objects
+to have inlets or outlets you need need to set those fields in this
+method (Pd doesn't support changing the number of inlets or outlets
+after an object is created):;
+#X text 31 699 The default inlet/outlet counts are 0;
+#X text 31 732 The return value of 'initialize' is used to allow objects
+to fail to create (for example \, if the creation arguments are bad).
+Most of the time you will 'return true' \, but if you really can't
+create then you can 'return false'.;
+#X text 31 920 The 'finalize' method is called when the object is deleted
+by Pd. You can clean up stuff here if needed. The default implementation
+does nothing.;
+#X text 31 1620 You can send messages to receivers like this:;
+#X text 31 567 where <> should be curly brackets \, but Pd won't print
+them in a comment.;
+#X text 30 1661 (again the <> represent curly brackets);
+#X text 32 1782 Remember to clean up your receivers in object:finalize()
+\, or weird things will happen.;
+#X obj 13 1823 cnv 15 400 120 empty empty Clocks 20 12 0 14 -203904
+-66577 0;
+#X obj 13 1944 cnv 15 400 120 empty empty Miscellaneous_Object_Methods
+20 12 0 14 -261234 -66577 0;
+#X text 32 1843 You can bind methods to clocks \, for timing based
+on Pd's logical clock.;
+#X text 32 1886 Remember to clean up your clocks in object:finalize()
+\, or weird things will happen.;
+#X text 31 1964 Execute a Lua file using Pd's path to find it:;
+#X text 31 2001 Report an error to Pd's console:;
+#X obj 13 2065 cnv 15 400 120 empty empty Miscellaneous_Functions 20
+12 0 14 -135137 -66577 0;
+#X text 31 2088 Print a string to Pd's console:;
+#X text 31 2124 Note that pd.post() should not really be used for errors.
+;
+#X text 31 2145 FIXME: add pd.error() for error messages;
+#X obj 9 2198 pdlua;
+#X obj 9 6 bng 15 250 50 0 empty empty empty 17 7 0 10 -262144 -1 -1
+;
+#X text 31 1724 You can bind methods to receivers \, to get messages
+from [send receiver] and " \; receiver message".;
+#X obj 389 1900 bng 15 250 50 0 empty empty empty 17 7 0 10 -13381
+-4034 -1;
+#X obj 48 195 cnv 15 300 20 empty empty empty 20 12 0 14 -204786 -66577
+0;
+#X text 57 197 local foo = pd.Class:new():register("foo");
+#X obj 48 368 cnv 15 300 50 empty empty empty 20 12 0 14 -204786 -66577
+0;
+#X obj 48 437 cnv 15 300 50 empty empty empty 20 12 0 14 -204786 -66577
+0;
+#X text 55 367 function foo:initialize(sel \, atoms);
+#X text 56 380 -- code;
+#X text 56 394 end;
+#X text 56 436 foo.initialize = function (self \, sel \, atoms);
+#X text 55 450 -- code;
+#X text 56 463 end;
+#X obj 48 844 cnv 15 300 50 empty empty empty 20 12 0 14 -204786 -66577
+0;
+#X obj 48 666 cnv 15 300 30 empty empty empty 20 12 0 14 -204786 -66577
+0;
+#X text 48 551 <"a" \, "b" \, 1 \, 2 \, 3 \, "c">;
+#X text 56 664 self.inlets = 1;
+#X text 56 680 self.outlets = atoms[1];
+#X text 55 843 function foo:postinitialize();
+#X text 55 857 -- code;
+#X text 56 872 end;
+#X obj 48 1982 cnv 15 300 20 empty empty empty 20 12 0 14 -204786 -66577
+0;
+#X obj 48 2025 cnv 15 300 20 empty empty empty 20 12 0 14 -204786 -66577
+0;
+#X obj 48 2105 cnv 15 300 20 empty empty empty 20 12 0 14 -204786 -66577
+0;
+#X text 56 1982 self:dofile("filename");
+#X text 56 2025 self:error("message");
+#X text 56 2105 pd.post("a string");
+#X obj 389 1663 bng 15 250 50 0 empty empty empty 17 7 0 10 -4034 -257985
+-1;
+#X floatatom 512 1789 5 0 0 0 - - -;
+#X msg 424 1614 1000;
+#X msg 462 1614 100;
+#X text 32 1761 See doc/examples/lreceive.pd_lua for details.;
+#X text 32 1682 See doc/examples/lsend.pd_lua for details.;
+#X text 32 1871 See doc/examples/ldelay.pd_lua for details.;
+#X obj 389 1685 lsend splat-1;
+#X obj 424 1667 lsend splat-2;
+#X obj 389 1760 lreceive splat- 1 2 3;
+#X obj 389 1870 ldelay 1000;
+#X text 75 2183 modified from doc/examples/pdlua/lua.txt;
+#X text 75 2196 by mrpeach 2011/10/05;
+#X text 31 994 Each inlet should have at least one method that will
+be called when an item it can handle arrives at that input.;
+#X obj 48 1080 cnv 15 300 50 empty empty empty 20 12 0 14 -204786 -66577
+0;
+#X text 55 1084 function foo:in_1_float(f);
+#X text 54 1097 -- code;
+#X text 56 1110 end;
+#X obj 48 1153 cnv 15 300 50 empty empty empty 20 12 0 14 -204786 -66577
+0;
+#X text 54 1170 -- code;
+#X text 56 1183 end;
+#X obj 48 1227 cnv 15 300 50 empty empty empty 20 12 0 14 -204786 -66577
+0;
+#X text 54 1244 -- code;
+#X text 56 1257 end;
+#X text 32 1206 A "gimme" method for [foo] accepts any input:;
+#X text 55 1231 function foo:in_1(sel \, atoms);
+#X obj 44 712 bng 15 250 50 0 empty empty empty 17 7 0 10 -262144 -1
+-1;
+#X obj 44 1716 tgl 15 0 empty empty empty 17 7 0 10 -262144 -1 -1 0
+1;
+#X text 31 1455;
+#X obj 48 1428 cnv 15 300 20 empty empty empty 20 12 0 14 -204786 -66577
+0;
+#X text 55 1432 self:outlet(2 \, "bang" \, <>);
+#X text 29 1451 (as usual <> should be curly brackets);
+#X text 31 1403 This will cause the second outlet to emit a bang:;
+#X obj 48 1498 cnv 15 300 20 empty empty empty 20 12 0 14 -204786 -66577
+0;
+#X text 31 1473 This will cause the second outlet to emit a float:
+;
+#X text 55 1502 self:outlet(2 \, "float" \, <123>);
+#X obj 48 1548 cnv 15 300 40 empty empty empty 20 12 0 14 -204786 -66577
+0;
+#X text 31 1523 This will cause the first outlet to emit a list:;
+#X text 55 1569 self:outlet(1 \, "list" \, somelist);
+#X text 55 1552 self.somelist = <some items in a list>;
+#X text 32 1132 A "stop" method for inlet 2 of [foo]:;
+#X text 55 1157 function foo:in_2_stop();
+#X text 31 1024 The name of the method is constructed as "in_n_selector"
+where n is the inlet number (starting from 1) and selector is a type
+such as "float" or "bang" \, or a selector name such as "start". Here
+is a float method for [foo] inlet 1:;
+#X obj 48 1639 cnv 15 360 20 empty empty empty 20 12 0 14 -204786 -66577
+0;
+#X text 55 1639 pd.send("receiver" \, "selector" \, <"a" \, "message"
+\, 1 \, 2 \, 3>;
+#X obj 48 1301 cnv 15 300 50 empty empty empty 20 12 0 14 -204786 -66577
+0;
+#X text 54 1318 -- code;
+#X text 56 1331 end;
+#X text 32 1280 A method for symbols on any input:;
+#X text 55 1305 function foo:in_n_symbol(i \, s);
+#X text 31 786 If you need to do things after the Pd object is created
+\, but before control is returned to Pd \, (such as registering receivers
+or clocks) you can use the 'postinitialize' method:;
+#X connect 38 0 37 0;
+#X connect 65 0 72 0;
+#X connect 67 0 73 0;
+#X connect 68 0 73 0;
+#X connect 74 0 75 0;
+#X connect 74 1 66 0;
+#X connect 75 0 40 0;
+#X connect 91 0 92 0;
+#X restore 282 90 pd pdlua_HOWTO;
+#X connect 0 0 8 0;
+#X connect 4 0 8 0;