X-Git-Url: https://git.carlh.net/gitweb/?a=blobdiff_plain;f=tools%2Ffmt-luadoc.php;h=b13e38617caf77f2b7c31a75ca67ba958f20d006;hb=aa8128cdf526c8f10b39ad4362101e4760be3319;hp=279225816aba387e4d328cb2d897ed45197f3f3e;hpb=e105d50d66a06c8077379782e8293b40338b5293;p=ardour.git diff --git a/tools/fmt-luadoc.php b/tools/fmt-luadoc.php index 279225816a..b13e38617c 100755 --- a/tools/fmt-luadoc.php +++ b/tools/fmt-luadoc.php @@ -2,20 +2,51 @@ doc/luadoc.json +# ./gtk2_ardour/arluadoc > doc/luadoc.json.gz # +## generate doc/ardourapi.json.gz (ardour header doxygen doc) +# cd ../../tools/doxy2json +# ./ardourdoc.sh +# cd - +# +## format HTML (using this scripterl) # php tools/fmt-luadoc.php > /tmp/luadoc.html # +$options = getopt("m"); +if (isset ($options['m'])) { + $HTMLOUTPUT = false; ## set to false to output ardour-manual +} else { + $HTMLOUTPUT = true; ## set to false to output ardour-manual +} + ################################################################################ ################################################################################ -$json = file_get_contents (dirname (__FILE__).'/../doc/luadoc.json'); +$json = gzdecode (file_get_contents (dirname (__FILE__).'/../doc/luadoc.json.gz')); $doc = array (); +$ardourversion = ''; foreach (json_decode ($json, true) as $b) { - if (!isset ($b['type'])) { continue; } + if (!isset ($b['type'])) { + if (isset ($b['version'])) { $ardourversion = $b['version']; } + continue; + } + # reserved lua words + $b ['lua'] = preg_replace ('/:_end/', ':end', $b ['lua']); + $b ['lua'] = preg_replace ('/:_type/', ':type', $b ['lua']); + $b ['ldec'] = preg_replace ('/ const/', '', preg_replace ('/ const&/', '', $b['decl'])); + $b ['ldec'] = preg_replace ('/_VampHost::/', '', $b['ldec']); + $b ['decl'] = preg_replace ('/_VampHost::/', '', $b['decl']); + if (isset ($b['ret'])) { + $b['ret'] = preg_replace ('/ const/', '', preg_replace ('/ const&/', '', $b['ret'])); + $b['ret'] = preg_replace ('/_VampHost::/', '', $b['ret']); + } + if (isset ($b['parent'])) { + $b ['parent'] = preg_replace ('/_VampHost::/', '', $b['parent']); + } $doc[] = $b; } @@ -56,23 +87,28 @@ function my_die ($msg) { # return preg_replace ('/boost::shared_ptr<([^>]*)[ ]*>/', '$1', $ctype); #} -function arg2lua ($argtype) { +function arg2lua ($argtype, $flags = 0) { global $classes; global $consts; # LuaBridge abstracts C++ references - $flags = preg_match ('/&$/', $argtype); + $flags |= preg_match ('/&$/', $argtype); $arg = preg_replace ('/&$/', '', $argtype); + $arg = preg_replace ('/ $/', '', $arg); # filter out basic types - $builtin = array ('float', 'double', 'bool', 'std::string', 'int', 'long', 'unsigned long', 'unsigned int', 'unsigned char', 'char', 'void', 'char*', 'unsigned char*', 'void*'); + $builtin = array ('float', 'double', 'bool', 'std::string', 'int', 'short', 'long', 'unsigned int', 'unsigned short', 'unsigned long', 'unsigned char', 'char', 'void', 'char*', 'unsigned char*', 'void*'); if (in_array ($arg, $builtin)) { return array ($arg => $flags); } + if ($arg == 'luabridge::LuaRef') { + return array ('Lua-Function' => $flags | 4); + } + # check Class declarations first foreach (array_merge ($classes, $consts) as $b) { - if ($b['decl'] == $arg) { + if ($b['ldec'] == $arg) { return array ($b['lua'] => $flags); } } @@ -80,11 +116,15 @@ function arg2lua ($argtype) { # strip class pointers -- TODO Check C'tor for given class $arg = preg_replace ('/[&*]*$/', '', $argtype); foreach (array_merge ($classes, $consts) as $b) { - if ($b['decl'] == $arg) { + if ($b['ldec'] == $arg) { return array ($b['lua'] => $flags); } } - return array ('--MISSING (' . $argtype . ')--' => ($flags | 4)); + if ($flags & 2) { + return array ($argtype => ($flags | 4)); + } else { + return array ('--MISSING (' . $argtype . ')--' => ($flags | 4)); + } } function stripclass ($classname, $name) { @@ -98,13 +138,22 @@ function stripclass ($classname, $name) { function datatype ($decl) { # TODO handle spaces in type. Works because # we don't yet have templated types (with_space ) - return substr ($decl, 0, strpos ($decl, ' ')); + return substr ($decl, 0, strrpos ($decl, ' ')); } function luafn2class ($lua) { return substr ($lua, 0, strrpos ($lua, ':')); } +function luafn2name ($lua) { + $fn = strrpos ($lua, ':'); + if ($fn !== 0 && strlen($lua) > $fn + 1) { + return substr ($lua, $fn + 1); + } + my_die ('invalid class prefix: '. $name); +} + + function checkclass ($b) { global $classlist; if (!isset ($classlist[luafn2class ($b['lua'])])) { @@ -126,6 +175,48 @@ function decl2args ($decl) { return $rv; } +function canonical_ctor ($b) { + $rv = ''; + if (preg_match('/[^(]*\(([^)*]*)\*\)(\(.*\))/', $b['decl'], $matches)) { + $lc = luafn2class ($b['lua']); + $cn = str_replace (':', '::', $lc); + $fn = substr ($lc, 1 + strrpos ($lc, ':')); + $rv = $cn . '::'. $fn . $matches[2]; + } + return $rv; +} + +function canonical_decl ($b) { + $rv = ''; + $pfx = ''; + # match clang's declatation format + if (preg_match('/[^(]*\(([^)*]*)\*\)\((.*)\)/', $b['decl'], $matches)) { + if (strpos ($b['type'], 'Free Function') !== false) { + $pfx = str_replace (':', '::', luafn2class ($b['lua'])) . '::'; + } + $fn = substr ($b['lua'], 1 + strrpos ($b['lua'], ':')); + $rv = $matches[1] . $fn . '('; + $arglist = preg_split ('/, */', $matches[2]); + $first = true; + foreach ($arglist as $a) { + if (!$first) { $rv .= ', '; }; $first = false; + if (empty ($a)) { continue; } + $a = preg_replace ('/([^>]) >/', '$1>', $a); + $a = preg_replace ('/^Cairo::/', '', $a); // special case cairo enums + $a = preg_replace ('/([^ ])&/', '$1 &', $a); + $a = preg_replace ('/std::vector<([^>]*)> const/', 'const std::vector<$1>', $a); + $a = str_replace ('std::vector', 'vector', $a); + $a = str_replace ('vector', 'std::vector', $a); + $a = str_replace ('std::string', 'string', $a); + $a = str_replace ('string const', 'const string', $a); + $a = str_replace ('string', 'std::string', $a); + $rv .= $a; + } + $rv .= ')'; + } + return $pfx . $rv; +} + ################################################################################ # step 1: build class indices @@ -134,7 +225,7 @@ foreach ($doc as $b) { $classes[] = $b; $classlist[$b['lua']] = $b; if (strpos ($b['type'], 'Pointer Class') === false) { - $classdecl[$b['decl']] = $b; + $classdecl[$b['ldec']] = $b; } } } @@ -155,11 +246,11 @@ foreach ($doc as $b) { switch ($b['type']) { case "Constant/Enum": case "Constant/Enum Member": - if (strpos ($b['decl'], '::') === false) { + if (strpos ($b['ldec'], '::') === false) { # for extern c enums, use the Lua Namespace - $b['decl'] = str_replace (':', '::', luafn2class ($b['lua'])); + $b['ldec'] = str_replace (':', '::', luafn2class ($b['lua'])); } - $ns = str_replace ('::', ':', $b['decl']); + $ns = str_replace ('::', ':', $b['ldec']); $constlist[$ns][] = $b; # arg2lua lookup $b['lua'] = $ns; @@ -178,30 +269,68 @@ foreach ($doc as $b) { checkclass ($b); $classlist[luafn2class ($b['lua'])]['ctor'][] = array ( 'name' => luafn2class ($b['lua']), - 'args' => decl2args ($b['decl']), + 'args' => decl2args ($b['ldec']), + 'cand' => canonical_ctor ($b), + 'nil' => false + ); + break; + case "Weak/Shared Pointer NIL Constructor": + checkclass ($b); + $classlist[luafn2class ($b['lua'])]['ctor'][] = array ( + 'name' => luafn2class ($b['lua']), + 'args' => decl2args ($b['ldec']), + 'cand' => canonical_ctor ($b), + 'nil' => true + ); + break; + case "Property": + checkclass ($b); + $classlist[luafn2class ($b['lua'])]['props'][] = array ( + 'name' => $b['lua'], + 'ret' => arg2lua (datatype ($b['ldec'])) ); break; case "Data Member": checkclass ($b); $classlist[luafn2class ($b['lua'])]['data'][] = array ( 'name' => $b['lua'], - 'ret' => arg2lua (datatype ($b['decl'])) + 'ret' => arg2lua (datatype ($b['ldec'])) + ); + break; + case "Static C Function": + checkclass ($b); + if (strpos ($b['lua'], 'ARDOUR:DataType:') === 0) { + # special case ARDOUR:DataType convenience c'tor + $args = array (); + $ret = array (luafn2class ($b['lua']) => 0); + $canon = 'ARDOUR::LuaAPI::datatype_ctor_'.strtolower (luafn2name ($b['lua'])).'(lua_State*)'; + } else { + my_die ('unhandled Static C: ' . print_r($b, true)); + } + $classlist[luafn2class ($b['lua'])]['func'][] = array ( + 'bind' => $b, + 'name' => $b['lua'], + 'args' => $args, + 'ret' => $ret, + 'ref' => false, + 'ext' => false, + 'cand' => $canon ); break; case "C Function": # we required C functions to be in a class namespace case "Ext C Function": checkclass ($b); - $args = array (array ('--custom--' => 0)); + $args = array (array ('--lua--' => 0)); $ret = array ('...' => 0); $ns = luafn2class ($b['lua']); $cls = $classlist[$ns]; - ## std::Vector std::List types - if (preg_match ('/.*<([^>]*)[ ]*>/', $cls['decl'], $templ)) { - // XXX -> move to C-source + if (preg_match ('/.*<([^>]*)[ ]*>/', $cls['ldec'], $templ)) { + # std::vector, std::list types switch (stripclass($ns, $b['lua'])) { case 'add': - $args = array (array ('LuaTable {'.$templ[1].'}' => 0)); + #$args = array (array ('LuaTable {'.$templ[1].'}' => 0)); + $args = array (arg2lua ($templ[1], 2)); $ret = array ('LuaTable' => 0); break; case 'iter': @@ -216,7 +345,8 @@ foreach ($doc as $b) { break; } } else if (strpos ($cls['type'], ' Array') !== false) { - $templ = preg_replace ('/[&*]*$/', '', $cls['decl']); + # catches C:FloatArray, C:IntArray + $templ = preg_replace ('/[&*]*$/', '', $cls['ldec']); switch (stripclass($ns, $b['lua'])) { case 'array': $args = array (); @@ -240,7 +370,19 @@ foreach ($doc as $b) { 'args' => $args, 'ret' => $ret, 'ref' => true, - 'ext' => true + 'ext' => true, + 'cand' => canonical_decl ($b) + ); + break; + case "Free C Function": + $funclist[luafn2class ($b['lua'])][] = array ( + 'bind' => $b, + 'name' => $b['lua'], + 'args' => $args, + 'ret' => $ret, + 'ref' => false, + 'ext' => true, + 'cand' => str_replace (':', '::', $b['lua']).'(lua_State*)' ); break; case "Free Function": @@ -248,9 +390,10 @@ foreach ($doc as $b) { $funclist[luafn2class ($b['lua'])][] = array ( 'bind' => $b, 'name' => $b['lua'], - 'args' => decl2args ($b['decl']), + 'args' => decl2args ($b['ldec']), 'ret' => arg2lua ($b['ret']), - 'ref' => (strpos ($b['type'], "RefReturn") !== false) + 'ref' => (strpos ($b['type'], "RefReturn") !== false), + 'cand' => canonical_decl ($b) ); break; case "Member Function": @@ -259,15 +402,27 @@ foreach ($doc as $b) { case "Weak/Shared Pointer Function": case "Weak/Shared Pointer Function RefReturn": case "Weak/Shared Null Check": - case "Weak/Shared Pointer Cast": case "Static Member Function": checkclass ($b); $classlist[luafn2class ($b['lua'])]['func'][] = array ( 'bind' => $b, 'name' => $b['lua'], - 'args' => decl2args ($b['decl']), + 'args' => decl2args ($b['ldec']), + 'ret' => arg2lua ($b['ret']), + 'ref' => (strpos ($b['type'], "RefReturn") !== false), + 'cand' => canonical_decl ($b) + ); + break; + case "Cast": + case "Weak/Shared Pointer Cast": + checkclass ($b); + $classlist[luafn2class ($b['lua'])]['cast'][] = array ( + 'bind' => $b, + 'name' => $b['lua'], + 'args' => decl2args ($b['ldec']), 'ret' => arg2lua ($b['ret']), - 'ref' => (strpos ($b['type'], "RefReturn") !== false) + 'ref' => (strpos ($b['type'], "RefReturn") !== false), + 'cand' => canonical_decl ($b) ); break; case "Constant/Enum": @@ -289,14 +444,17 @@ foreach ($doc as $b) { foreach ($classlist as $ns => $cl) { if (strpos ($cl['type'], ' Array') !== false) { $classlist[$ns]['arr'] = true; + $classlist[$ns]['cdecl'] = $cl['decl']; continue; } foreach ($classes as $c) { if ($c['lua'] == $ns) { if (strpos ($c['type'], 'Pointer Class') !== false) { $classlist[$ns]['ptr'] = true; - $classlist[$ns]['decl'] = 'boost::shared_ptr< '.$c['decl']. ' >, boost::weak_ptr< '.$c['decl']. ' >'; + $classlist[$ns]['cdecl'] = 'boost::shared_ptr< '.$c['decl']. ' >, boost::weak_ptr< '.$c['decl']. ' >'; break; + } else { + $classlist[$ns]['cdecl'] = $c['decl']; } } } @@ -331,11 +489,45 @@ ksort ($classlist); #### -- split here -- #### # from here on, only $classlist and $constlist arrays are relevant. +# we also pull in C++ header annotation from doxygen to $api -# TODO: read function documentation from doxygen -# and/or reference source-code lines e.g from CSV list: -# ctags -o /tmp/tags.csv --fields=+afiKkmnsSzt libs/ardour/ardour/session.h +# read documentation from doxygen +$json = gzdecode (file_get_contents (dirname (__FILE__).'/../doc/ardourapi.json.gz')); +$api = array (); +foreach (json_decode ($json, true) as $a) { + if (!isset ($a['decl'])) { continue; } + if (empty ($a['decl'])) { continue; } + $canon = str_replace (' *', '*', $a['decl']); + $api[$canon] = $a; +} + +# keep track of found/missing doc +$dox_found = 0; +$dox_miss = 0; + +# retrive a value from $api +function doxydoc ($canonical_declaration) { + global $api; + global $dox_found; + global $dox_miss; + if (isset ($api[$canonical_declaration])) { + $dox_found++; + return $api[$canonical_declaration]['doc']; + } + // remove template namespace e.g. + // "ARDOUR::Track::bounceable(boost::shared_ptr" + // "ARDOUR::Track::bounceable(boost::shared_ptr" + $cn = preg_replace ('/<[^>]*::([^>]*)>/', '<$1>', $canonical_declaration); + if (isset ($api[$cn])) { + $dox_found++; + return $api[$cn]['doc']; + } + #fwrite (STDERR, $canonical_declaration."\n"); # XXX DEBUG + + $dox_miss++; + return ''; +} ################################################################################ # OUTPUT @@ -346,22 +538,22 @@ ksort ($classlist); # Helper functions define ('NL', "\n"); +# constructors, enums (constants) use a dot. (e.g. "LuaOSC.Address" -> "LuaOSC.Address" ) function ctorname ($name) { return htmlentities (str_replace (':', '.', $name)); } +# strip class prefix (e.g "Evoral:MidiEvent:channel" -> "channel") function shortname ($name) { return htmlentities (substr ($name, strrpos ($name, ':') + 1)); } +# retrieve variable name from array["VARNAME"] => FLAGS function varname ($a) { return array_keys ($a)[0]; } -function name_sort_cb ($a, $b) { - return strcmp ($a['name'], $b['name']); -} - +# recusively collect class parents (derived classes) function traverse_parent ($ns, &$inherited) { global $classlist; $rv = ''; @@ -370,6 +562,7 @@ function traverse_parent ($ns, &$inherited) { asort ($parents); foreach ($parents as $p) { if (!empty ($rv)) { $rv .= ', '; } + if ($p == $ns) { continue; } $rv .= typelink ($p); $inherited[$p] = $classlist[$p]; traverse_parent ($p, $inherited); @@ -378,11 +571,11 @@ function traverse_parent ($ns, &$inherited) { return $rv; } +# create a cross-reference to a type (class or enum) +# *all* links are generated here, currently anchors on a single page. function typelink ($a, $short = false, $argcls = '', $linkcls = '', $suffix = '') { global $classlist; global $constlist; - # all cross-reference links are generated here. - # currently anchors on a single page. if (isset($classlist[$a]['free'])) { return ''.($short ? shortname($a) : ctorname($a)).$suffix.''; } else if (in_array ($a, array_keys ($classlist))) { @@ -394,15 +587,23 @@ function typelink ($a, $short = false, $argcls = '', $linkcls = '', $suffix = '' } } +# output format function arguments function format_args ($args) { $rv = ' ('; $first = true; foreach ($args as $a) { if (!$first) { $rv .= ', '; }; $first = false; $flags = $a[varname ($a)]; - if ($flags & 1) { + if ($flags & 4) { + $rv .= ''.varname ($a).''; + } + else if ($flags & 2) { + $rv .= 'LuaTable {'.typelink (varname ($a), true, 'em').'}'; + } + elseif ($flags & 1) { $rv .= typelink (varname ($a), true, 'em', '', '&'); - } else { + } + else { $rv .= typelink (varname ($a), true, 'em'); } } @@ -410,18 +611,65 @@ function format_args ($args) { return $rv; } +# format doxygen documentation for class-definition +function format_doxyclass ($cl) { + $rv = ''; + if (isset ($cl['decl'])) { + $doc = doxydoc ($cl['decl']); + if (!empty ($doc)) { + $rv.= '
'.$doc.'
'.NL; + } + } + return $rv; +} + +# format doxygen documentation for class-members +function format_doxydoc ($f) { + $rv = ''; + if (isset ($f['cand'])) { + $doc = doxydoc ($f['cand']); + if (!empty ($doc)) { + $rv.= '
'.$doc; + $rv.= '
'.NL; + } else if (0) { # debug + $rv.= '

'.htmlentities($f['cand']).'

'; + $rv.= ''.NL; + } + } + return $rv; +} + +# usort() callback for class-members +function name_sort_cb ($a, $b) { + return strcmp ($a['name'], $b['name']); +} + +# main output function for every class function format_class_members ($ns, $cl, &$dups) { $rv = ''; + # print contructor - if any if (isset ($cl['ctor'])) { usort ($cl['ctor'], 'name_sort_cb'); $rv.= ' Constructor'.NL; foreach ($cl['ctor'] as $f) { - $rv.= ' ℂ'; + $rv.= ' '; + if ($f['nil']) { + $rv.= 'ℵ'; + } else { + $rv.= 'ℂ'; + } + $rv.= ''; $rv.= ''.ctorname ($f['name']).''; $rv.= format_args ($f['args']); $rv.= ''.NL; + # doxygen documentation (may be empty) + $rv.= format_doxydoc($f); } } + + # strip duplicates (inherited or derived methods) + # e.g AudioTrack -> Track -> Route -> SessionObject -> Stateful + # all 5 have "isnil()" $nondups = array (); if (isset ($cl['func'])) { foreach ($cl['func'] as $f) { @@ -429,29 +677,66 @@ function format_class_members ($ns, $cl, &$dups) { $nondups[] = $f; } } + + # print methods - if any if (count ($nondups) > 0) { usort ($nondups, 'name_sort_cb'); $rv.= ' Methods'.NL; foreach ($nondups as $f) { $dups[] = stripclass ($ns, $f['name']); + # return value/type $rv.= ' '; if ($f['ref'] && isset ($f['ext'])) { # external C functions $rv.= ''.varname ($f['ret']).''; } elseif ($f['ref'] && varname ($f['ret']) == 'void') { - # functions with reference args return args + # void functions with reference args $rv.= 'LuaTable(...)'; } elseif ($f['ref']) { - $rv.= 'LuaTable('.typelink (varname ($f['ret'], false, 'em')).', ...)'; + # functions with reference args and return value + $rv.= 'LuaTable('.typelink (varname ($f['ret']), true, 'em').', ...)'; } else { + # normal class members $rv.= typelink (varname ($f['ret']), true, 'em'); } + # function declaration and arguments + $rv.= ''; + $rv.= ''.stripclass ($ns, $f['name']).''; + $rv.= format_args ($f['args']); + $rv.= ''.NL; + # doxygen documentation (may be empty) + $rv.= format_doxydoc($f); + } + } + # print cast - if any + if (isset ($cl['cast'])) { + usort ($cl['cast'], 'name_sort_cb'); + $rv.= ' Cast'.NL; + foreach ($cl['cast'] as $f) { + $rv.= ' '; + $rv.= typelink (varname ($f['ret']), true, 'em'); + # function declaration and arguments $rv.= ''; $rv.= ''.stripclass ($ns, $f['name']).''; $rv.= format_args ($f['args']); $rv.= ''.NL; + # doxygen documentation (may be empty) + $rv.= format_doxydoc($f); } } + + # print properties - if any + if (isset ($cl['props'])) { + usort ($cl['props'], 'name_sort_cb'); + $rv.= ' Properties'.NL; + foreach ($cl['props'] as $f) { + $rv.= ' '.typelink (array_keys ($f['ret'])[0], false, 'em').''; + $rv.= ''.stripclass ($ns, $f['name']).''; + $rv.= ''.NL; + } + } + + # print data members - if any if (isset ($cl['data'])) { usort ($cl['data'], 'name_sort_cb'); $rv.= ' Data Members'.NL; @@ -459,6 +744,8 @@ function format_class_members ($ns, $cl, &$dups) { $rv.= ' '.typelink (array_keys ($f['ret'])[0], false, 'em').''; $rv.= ''.stripclass ($ns, $f['name']).''; $rv.= ''.NL; + $f['cand'] = str_replace (':', '::', $f['name']); + $rv.= format_doxydoc($f); } } return $rv; @@ -468,40 +755,63 @@ function format_class_members ($ns, $cl, &$dups) { ################################################################################ # Start Output +if ($HTMLOUTPUT) { + ?> Ardour Lua Bindings
-

Ardour Lua Bindings

+

Ardour Lua Bindings

Class Documentation  |  @@ -510,11 +820,35 @@ div.header p {margin:.25em;} Index

-
-

Overview

+ + + + +

+This documentation is far from complete may be inaccurate and subject to change. +

+ + + +
+ + + +

Overview

-The top-level entry point are and . +The top-level entry point are and . Most other Classes are used indirectly starting with a Session function. e.g. Session:get_routes().

@@ -525,55 +859,169 @@ A few classes are dedicated to certain script types, e.g. Lua DSP processors hav

Detailed documentation (parameter names, method description) is not yet available. Please stay tuned.

+

Short introduction to Ardour classes

+

+Ardour's structure is object oriented. The main object is the Session. A Session contains Audio Tracks, Midi Tracks and Busses. +Audio and Midi tracks are derived from a more general "Track" Object, which in turn is derived from a "Route" (aka Bus). +(We say "An Audio Track is-a Track is-a Route"). +Tracks contain specifics. For Example a track has-a diskstream (for file i/o). +

+

+Operations are performed on objects. One gets a reference to an object and then calls a method. +e.g obj = Session:route_by_name("Audio") obj:set_name("Guitar"). +

+

+Lua automatically follows C++ class inheritance. e.g one can directly call all SessionObject and Route methods on Track object. However lua does not automatically promote objects. A Route object which just happens to be a Track needs to be explicily cast to a Track. Methods for casts are provided with each class. Note that the cast may fail and return a nil reference. +

+

+Likewise multiple inheritance is a non-trivial issue in lua. To avoid performance penalties involved with lookups, explicit casts are required in this case. One example is which is-a StatefulDestructible which inhertis from both Stateful and Destructible. +

+

+Object lifetimes are managed by the Session. Most Objects cannot be directly created, but one asks the Session to create or destroy them. This is mainly due to realtime constrains: +you cannot simply remove a track that is currently processing audio. There are various factory methods for object creation or removal. +

+

Pass by Reference

+

+Since lua functions are closures, C++ methods that pass arguments by reference cannot be used as-is. +All parameters passed to a C++ method which uses references are returned as Lua Table. +If the C++ method also returns a value it is prefixed. Two parameters are returned: the value and a Lua Table holding the parameters. +

+ +
+
C++ + +
void set_ref (int& var, long& val)
+{
+	printf ("%d %ld\n", var, val);
+	var = 5;
+	val = 7;
+}
+
+ +
+
Lua + +
local var = 0;
+ref = set_ref (var, 2);
+-- output from C++ printf()
+0 2
+-- var is still 0 here
+print (ref[1], ref[2])
+5 7
+ +
+
+
+
+
+ +
int set_ref2 (int &var, std::string unused)
+{
+	var = 5;
+	return 3;
+}
+
+ +
+
+
rv, ref = set_ref2 (0, "hello");
+print (rv, ref[1], ref[2])
+3 5 hello
+
+
+
+ +

Pointer Classes

+

+Libardour makes extensive use of reference counted boost::shared_ptr to manage lifetimes. +The Lua bindings provide a complete abstration of this. There are no pointers in lua. +For example a is a pointer in C++, but lua functions operate on it like it was a class instance. +

+

+shared_ptr are reference counted. Once assigned to a lua variable, the C++ object will be kept and remains valid. +It is good practice to assign references to lua local variables or reset the variable to nil to drop the ref. +

+

+All pointer classes have a isnil () method. This is for two cases: +Construction may fail. e.g. .newplugin() +may not be able to find the given plugin and hence cannot create an object. +

+

+The second case if for boost::weak_ptr. As opposed to boost::shared_ptr weak-pointers are not reference counted. +The object may vanish at any time. +If lua code calls a method on a nil object, the interpreter will raise an exception and the script will not continue. +This is not unlike a = nil a:test() which results in en error "attempt to index a nil value". +

+

+From the lua side of things there is no distinction between weak and shared pointers. They behave identically. +Below they're inidicated in orange and have an arrow to indicate the pointer type. +Pointer Classes cannot be created in lua scripts. It always requires a call to C++ to create the Object and obtain a reference to it. +

+ Class Documentation'.NL; +################################# +# Main output function -- Classes + +echo '

Class Documentation

'.NL; foreach ($classlist as $ns => $cl) { $dups = array (); $tbl = format_class_members ($ns, $cl, $dups); - # format class title + # format class title - depending on type if (empty ($tbl)) { - echo '

∅ '.htmlentities ($ns).'

'.NL; + # classes with no members (no ctor, no methods, no data) + echo '

∅ '.htmlentities ($ns).'

'.NL; } else if (isset ($classlist[$ns]['free'])) { - echo '

ℕ '.ctorname($ns).'

'.NL; + # free functions (no class) + echo '

ℕ '.ctorname($ns).'

'.NL; } else if (isset ($classlist[$ns]['arr'])) { - echo '

⋯ '.htmlentities ($ns).'

'.NL; + # C Arrays + echo '

⋯ '.htmlentities ($ns).'

'.NL; } else if (isset ($classlist[$ns]['ptr'])) { - echo '

↠ '. htmlentities ($ns).'

'.NL; - } else { - echo '

∁ '.htmlentities ($ns).'

'.NL; + # Pointer Classes + echo '

↠ '. htmlentities ($ns).'

'.NL; } - if (isset ($cl['decl'])) { - echo '

C‡: '.htmlentities ($cl['decl']).'

'.NL; + else { + # Normal Class + echo '

∁ '.htmlentities ($ns).'

'.NL; } - # print class inheritance + # show original C++ declaration + if (isset ($cl['cdecl'])) { + echo '

C‡: '.htmlentities ($cl['cdecl']).'

'.NL; + } + + # print class inheritance (direct parent *name* only) $inherited = array (); $isa = traverse_parent ($ns, $inherited); if (!empty ($isa)) { - echo '

is-a: '.$isa.'

'.NL; + echo '

is-a: '.$isa.'

'.NL; } echo '
'.NL; + + # class documentation (if any) + echo format_doxyclass ($cl); + # member documentation if (empty ($tbl)) { - echo '

This class object is only used indirectly as return-value and function-parameter.

'.NL; + echo '

This class object is only used indirectly as return-value and function-parameter. It provides no methods by itself.

'.NL; } else { echo ''.NL; echo $tbl; echo '
'.NL; } - # traverse parent classes (inherited members) + # traverse parent classes (all inherited members) foreach ($inherited as $pns => $pcl) { $tbl = format_class_members ($pns, $pcl, $dups); if (!empty ($tbl)) { - echo '

Inherited from '.$pns.'

'.NL; + echo '

Inherited from '.$pns.'

'.NL; echo ''.NL; echo $tbl; echo '
'.NL; @@ -581,9 +1029,12 @@ foreach ($classlist as $ns => $cl) { } } -echo '

Enum/Constants

'.NL; +#################### +# Enum and Constants + +echo '

Enum/Constants

'.NL; foreach ($constlist as $ns => $cs) { - echo '

∈ '.ctorname ($ns).'

'.NL; + echo '

∈ '.ctorname ($ns).'

'.NL; echo '
    '.NL; foreach ($cs as $c) { echo '
  • '.ctorname ($c['lua']).'
    • '.NL; @@ -591,14 +1042,28 @@ foreach ($constlist as $ns => $cs) { echo '
'.NL; } -echo '

Class Index

'.NL; +###################### +# Index of all classes + +echo '

Class Index

'.NL; echo '
    '.NL; foreach ($classlist as $ns => $cl) { echo '
  • '.typelink($ns).'
    • '.NL; } echo '
'.NL; + +# see how far there is still to go... +fwrite (STDERR, "Found $dox_found annotations. missing: $dox_miss\n"); +echo ''.NL; + ?>
- - +
Ardour  - 
+'.NL; + echo ''.NL; + echo ''.NL; +}