From 7d3cb69c05bb79d7e8f7176521d325e1112bfb28 Mon Sep 17 00:00:00 2001 From: Martin Peach Date: Wed, 5 Oct 2011 21:23:18 +0000 Subject: Added a pdlua_HOWTO subpatch based on lua.txt svn path=/trunk/externals/loaders/pdlua/; revision=15523 --- src/pdlua-help.pd | 228 ++++++++++++++++++++++++++++++++++++++++++++++++++---- 1 file 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 = ; +#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; -- cgit v1.2.1