X-Git-Url: https://main.carlh.net/gitweb/?a=blobdiff_plain;f=tools%2Ffmt-luadoc.php;h=b13e38617caf77f2b7c31a75ca67ba958f20d006;hb=1dd4aab0b4d3e14ef93ddb3470d4c386f48cda6b;hp=bfb6b81ae57eb28bbc28624a6f01cbf1546c0186;hpb=c8db4fcfc642c6cc659757276a6796df0bc5f33f;p=ardour.git

diff --git a/tools/fmt-luadoc.php b/tools/fmt-luadoc.php
index bfb6b81ae5..b13e38617c 100755
--- a/tools/fmt-luadoc.php
+++ b/tools/fmt-luadoc.php
@@ -16,6 +16,13 @@
 # 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
+}
+
 ################################################################################
 ################################################################################
 
@@ -27,9 +34,18 @@ foreach (json_decode ($json, true) as $b) {
 		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;
 }
@@ -81,11 +97,15 @@ function arg2lua ($argtype, $flags = 0) {
 	$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['ldec'] == $arg) {
@@ -118,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 <here >)
-	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'])])) {
@@ -175,6 +204,8 @@ function canonical_decl ($b) {
 			$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);
@@ -239,7 +270,24 @@ foreach ($doc as $b) {
 		$classlist[luafn2class ($b['lua'])]['ctor'][] = array (
 			'name' => luafn2class ($b['lua']),
 			'args' => decl2args ($b['ldec']),
-			'cand' => canonical_ctor ($b)
+			'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":
@@ -249,6 +297,26 @@ foreach ($doc as $b) {
 			'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":
@@ -257,9 +325,8 @@ foreach ($doc as $b) {
 		$ret = array ('...' => 0);
 		$ns = luafn2class ($b['lua']);
 		$cls = $classlist[$ns];
-		## std::Vector std::List types
 		if (preg_match ('/.*<([^>]*)[ ]*>/', $cls['ldec'], $templ)) {
-			// XXX -> move to C-source
+			# std::vector, std::list types
 			switch (stripclass($ns, $b['lua'])) {
 			case 'add':
 				#$args = array (array ('LuaTable {'.$templ[1].'}' => 0));
@@ -278,6 +345,7 @@ foreach ($doc as $b) {
 				break;
 			}
 		} else if (strpos ($cls['type'], ' Array') !== false) {
+			# catches  C:FloatArray, C:IntArray
 			$templ = preg_replace ('/[&*]*$/', '', $cls['ldec']);
 			switch (stripclass($ns, $b['lua'])) {
 			case 'array':
@@ -306,6 +374,17 @@ foreach ($doc as $b) {
 			'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":
 	case "Free Function RefReturn":
 		$funclist[luafn2class ($b['lua'])][] = array (
@@ -323,7 +402,6 @@ 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 (
@@ -335,6 +413,18 @@ foreach ($doc as $b) {
 			'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),
+			'cand' => canonical_decl ($b)
+		);
+		break;
 	case "Constant/Enum":
 	case "Constant/Enum Member":
 		# already handled -> $consts
@@ -354,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'];
 			}
 		}
 	}
@@ -421,10 +514,19 @@ function doxydoc ($canonical_declaration) {
 	if (isset ($api[$canonical_declaration])) {
 		$dox_found++;
 		return $api[$canonical_declaration]['doc'];
-	} else {
-		$dox_miss++;
-		return '';
 	}
+	// remove template namespace e.g.
+	//  "ARDOUR::Track::bounceable(boost::shared_ptr<ARDOUR::Processor>"
+	//  "ARDOUR::Track::bounceable(boost::shared_ptr<Processor>"
+	$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 '';
 }
 
 ################################################################################
@@ -460,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);
@@ -491,7 +594,10 @@ function format_args ($args) {
 	foreach ($args as $a) {
 		if (!$first) { $rv .= ', '; }; $first = false;
 		$flags = $a[varname ($a)];
-		if ($flags & 2) {
+		if ($flags & 4) {
+			$rv .= '<span>'.varname ($a).'</span>';
+		}
+		else if ($flags & 2) {
 			$rv .= '<em>LuaTable</em> {'.typelink (varname ($a), true, 'em').'}';
 		}
 		elseif ($flags & 1) {
@@ -546,7 +652,13 @@ function format_class_members ($ns, $cl, &$dups) {
 		usort ($cl['ctor'], 'name_sort_cb');
 		$rv.= ' <tr><th colspan="3">Constructor</th></tr>'.NL;
 		foreach ($cl['ctor'] as $f) {
-			$rv.= ' <tr><td class="def">&Copf;</td><td class="decl">';
+			$rv.= ' <tr>';
+			if ($f['nil']) {
+				$rv.= '<td class="def"><abbr title="Nil Pointer Constructor">&alefsym;</abbr></td>';
+			} else {
+				$rv.= '<td class="def">&Copf;</td>';
+			}
+			$rv.= '<td class="decl">';
 			$rv.= '<span class="functionname">'.ctorname ($f['name']).'</span>';
 			$rv.= format_args ($f['args']);
 			$rv.= '</td><td class="fill"></td></tr>'.NL;
@@ -596,6 +708,34 @@ function format_class_members ($ns, $cl, &$dups) {
 			$rv.= format_doxydoc($f);
 		}
 	}
+	# print cast - if any
+	if (isset ($cl['cast'])) {
+		usort ($cl['cast'], 'name_sort_cb');
+		$rv.= ' <tr><th colspan="3">Cast</th></tr>'.NL;
+		foreach ($cl['cast'] as $f) {
+			$rv.= ' <tr><td class="def">';
+			$rv.= typelink (varname ($f['ret']), true, 'em');
+			# function declaration and arguments
+			$rv.= '</td><td class="decl">';
+			$rv.= '<span class="functionname"><abbr title="'.htmlentities($f['bind']['decl']).'">'.stripclass ($ns, $f['name']).'</abbr></span>';
+			$rv.= format_args ($f['args']);
+			$rv.= '</td><td class="fill"></td></tr>'.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.= ' <tr><th colspan="3">Properties</th></tr>'.NL;
+		foreach ($cl['props'] as $f) {
+			$rv.= ' <tr><td class="def">'.typelink (array_keys ($f['ret'])[0], false, 'em').'</td><td class="decl">';
+			$rv.= '<span class="functionname">'.stripclass ($ns, $f['name']).'</span>';
+			$rv.= '</td><td class="fill"></td></tr>'.NL;
+		}
+	}
+
 	# print data members - if any
 	if (isset ($cl['data'])) {
 		usort ($cl['data'], 'name_sort_cb');
@@ -604,6 +744,8 @@ function format_class_members ($ns, $cl, &$dups) {
 			$rv.= ' <tr><td class="def">'.typelink (array_keys ($f['ret'])[0], false, 'em').'</td><td class="decl">';
 			$rv.= '<span class="functionname">'.stripclass ($ns, $f['name']).'</span>';
 			$rv.= '</td><td class="fill"></td></tr>'.NL;
+			$f['cand'] = str_replace (':', '::', $f['name']);
+			$rv.= format_doxydoc($f);
 		}
 	}
 	return $rv;
@@ -613,6 +755,8 @@ function format_class_members ($ns, $cl, &$dups) {
 ################################################################################
 # Start Output
 
+if ($HTMLOUTPUT) {
+
 ?><!DOCTYPE html>
 <html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
 <head>
@@ -662,6 +806,7 @@ div.luafooter      { text-align:center; font-size:80%; color: #888; margin: 2em
 #luaref table.classmembers td.fill { width: 99%; }
 #luaref table.classmembers span.em { font-style: italic; }
 #luaref span.functionname abbr     { text-decoration:none; cursor:default; }
+#luaref table.classmembers td.def abbr { text-decoration:none; cursor:default; }
 </style>
 </head>
 <body>
@@ -676,7 +821,21 @@ div.luafooter      { text-align:center; font-size:80%; color: #888; margin: 2em
 </p>
 </div>
 
-<!-- #### SNIP  #### !-->
+<!-- #### SNIP #### !-->
+
+<?php
+
+} else {
+
+?>
+
+<p class="warning">
+This documentation is far from complete may be inaccurate and subject to change.
+</p>
+
+<?php
+}
+?>
 
 <div id="luaref">
 
@@ -712,6 +871,12 @@ Operations are performed on objects. One gets a reference to an object and then
 e.g <code>obj = Session:route_by_name("Audio")   obj:set_name("Guitar")</code>.
 </p>
 <p>
+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 <em>nil</em> reference.
+</p>
+<p>
+Likewise multiple inheritance is a <a href="http://www.lua.org/pil/16.3.html">non-trivial issue</a> in lua. To avoid performance penalties involved with lookups, explicit casts are required in this case. One example is <?=typelink('ARDOUR:SessionObject')?> which is-a StatefulDestructible which inhertis from both Stateful and Destructible.
+</p>
+<p>
 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 <em>factory</em> methods for object creation or removal.
 </p>
@@ -827,8 +992,8 @@ foreach ($classlist as $ns => $cl) {
 	}
 
 	# show original C++ declaration
-	if (isset ($cl['decl'])) {
-		echo '<p class="cdecl"><em>C&#8225;</em>: '.htmlentities ($cl['decl']).'</p>'.NL;
+	if (isset ($cl['cdecl'])) {
+		echo '<p class="cdecl"><em>C&#8225;</em>: '.htmlentities ($cl['cdecl']).'</p>'.NL;
 	}
 
 	# print class inheritance (direct parent *name* only)
@@ -890,12 +1055,15 @@ echo '</ul>'.NL;
 
 # see how far there is still to go...
 fwrite (STDERR, "Found $dox_found annotations. missing: $dox_miss\n");
+echo '<!-- '.$dox_found.' / '.$dox_miss.' !-->'.NL;
 
 ?>
 </div>
 <div class="luafooter">Ardour <?=$ardourversion?> &nbsp;-&nbsp; <?=date('r')?></div>
+<?php
 
-<!-- #### SNIP  #### !-->
-
-</body>
-</html>
+if ($HTMLOUTPUT) {
+	echo '<!-- #### SNIP #### !-->'.NL;
+	echo '</body>'.NL;
+	echo '</html>'.NL;
+}