[Laszlo-checkins] r11986 - in openlaszlo/trunk: WEB-INF/lps/lfc/compiler WEB-INF/lps/lfc/core WEB-INF/lps/lfc/debugger WEB-INF/lps/lfc/views lps/components/debugger
ptw@openlaszlo.org
ptw at openlaszlo.org
Fri Dec 5 11:01:41 PST 2008
Author: ptw
Date: 2008-12-05 11:01:36 -0800 (Fri, 05 Dec 2008)
New Revision: 11986
Modified:
openlaszlo/trunk/WEB-INF/lps/lfc/compiler/LzFormatter.lzs
openlaszlo/trunk/WEB-INF/lps/lfc/core/LzNode.lzs
openlaszlo/trunk/WEB-INF/lps/lfc/debugger/LzDebug.lzs
openlaszlo/trunk/WEB-INF/lps/lfc/debugger/LzMessage.lzs
openlaszlo/trunk/WEB-INF/lps/lfc/debugger/LzMonitor.lzs
openlaszlo/trunk/WEB-INF/lps/lfc/debugger/LzTrace.lzs
openlaszlo/trunk/WEB-INF/lps/lfc/views/LzText.lzs
openlaszlo/trunk/lps/components/debugger/library.lzx
Log:
Change 20081204-ptw-5 by ptw at dueling-banjos.home on 2008-12-04 13:51:43 EST
in /Users/ptw/OpenLaszlo/trunk
for http://svn.openlaszlo.org/openlaszlo/trunk
Summary: Improve formatToString documentation and examples
Bugs Fixed:
LPP-7437 Emphasize Debug.debug over Debug.write in documentation examples (partial)
Technical Reviewer: lou at louiorio.com (pending)
Details:
LzMessage, LzDebug, LzMonitor, LzTrace, LzText: Update type
declarations to something the doc tool will grok
LzDebug, LzText, LzFormatter: Update links to instance variables
since the doc tool does not know what to do with an xref.
LzNode, LzText: Add missing private declarations
LzFormatter: Add examples suggested in bug report. Improve the
documentation of formatToString. Make formatToString not complain
about extra arguments when using positional arguments.
debugger/library: Remove <>'s that were making the doc tool
whine. Improve the documentation to make it clearer that there
will not always be a debugger console window that you can
manipulate.
Tests:
smokecheck, examples from bug, ant doc and inspection
Modified: openlaszlo/trunk/WEB-INF/lps/lfc/compiler/LzFormatter.lzs
===================================================================
--- openlaszlo/trunk/WEB-INF/lps/lfc/compiler/LzFormatter.lzs 2008-12-05 19:00:50 UTC (rev 11985)
+++ openlaszlo/trunk/WEB-INF/lps/lfc/compiler/LzFormatter.lzs 2008-12-05 19:01:36 UTC (rev 11986)
@@ -12,12 +12,74 @@
/**
* Formatted output support
*
- * <p>See <xref linkend="LzText" />s <xref
- * linkend="LzText.prototype.format" /> and <xref linkend="LzDebugService+debug"
- * />s <xref linkend="LzDebugService+debug.prototype.format" /> methods for
+ * <p>See <xref linkend="LzText" /> and <xref linkend="LzDebugService+debug"
+ * /> for additional
* examples of how to present formatted text to the user
* interface.</p>
*
+ * <p>Here are some simple examples that show the use of the
+ * <code>s</code> and <code>w</code> conversions:</p>
+ * <example title="%s, %w, and %#w"><programlisting>
+<![CDATA[
+<canvas debug="true" height="150" width="100%">
+<debug y="5%" height="90%" />
+ <script>
+ var myObj = {a: 'eh?', b: 'bee', c: 'sea'};
+ Debug.debug("My object using %%s conversion: %s", myObj);
+ Debug.debug("My object using %%w conversion: %w", myObj);
+ Debug.debug("My object using %%#w conversion: %#w", myObj);
+ </script>
+</canvas>
+]]>
+ * </programlisting></example>
+ *
+ * <p>Here is an example showing how representations can be
+ * abbreviated. If you click on the abbreviated representation, you can inspect
+ * the entire object.</p>
+ * <example title="Abbreviating representations"><programlisting>
+<![CDATA[
+<canvas debug="true" height="150" width="100%">
+<debug y="5%" height="90%" />
+ <script>
+ var myObj = {one: 1, too: 2, 3: 'threeee', 42: "The answer", 'a very long tag name': "With a very long value to boot"};
+ Debug.write("My object using Debug.write:", myObj);
+ Debug.debug("My object using %%o.32w: %0.32w", myObj);
+ </script>
+</canvas>
+]]>
+ * </programlisting></example>
+ *
+ * <p>Here is an example showing how positional arguments could be
+ * used to accomodate parameterized control strings, say to support
+ * internationalizations where the values converted may have to be
+ * accessed in different orders.</p>
+ * <example title="Positional arguments"><programlisting>
+<![CDATA[
+<canvas layout="axis: y; spacing: 10" height="80" width="100%">
+ <debug y="5%" height="90%" />
+ <script>
+ var direction = {forward: "%1$s before %2$s", backward: "%2$s after %1$s"};
+ </script>
+ <text oninit="this.format(direction.forward, 'first', 'last')" />
+ <text oninit="this.format(direction.backward, 'first', 'last');"/>
+</canvas>
+]]>
+ * </programlisting></example>
+ *
+ * <p>Finally, here is an example of using a custom representation for
+ * an object</p>
+ * <example title="Custom object representation"><programlisting>
+<![CDATA[
+<canvas debug="true" height="150" width="100%">
+<debug y="5%" height="90%" />
+ <script>
+ var myObj = {a: "Complex", 'object with an': "ugly representation", 42: "The answer", length: 768};
+ Debug.debug("%=s <-- click for further details", myObj, 'Complex!')
+ </script>
+</canvas>
+]]>
+ * </programlisting></example>
+ *
* @access public
* @topic LZX
* @subtopic Formatted Output
@@ -26,8 +88,12 @@
/**
- * pad or trim a string to a specified length
+ * <p>Pad or trim a string to a specified length</p>
*
+ * <p>This is a support method <xref
+ * linkend="LzFormatter.prototype.formatToString" />, which is the
+ * preferred interface.</p>
+ *
* @param * value: the value to pad, will be coerced to a string if not a number
* @param Number widthMin: the minimum width, if negative pad on the
* right, default 0
@@ -119,36 +185,55 @@
}
/**
- * Formatted output to string
+ * <p>Formatted output to string</p>
*
- * Formats its arguments according to the control string.
+ * <p>Formats its arguments according to the control string.</p>
*
- * The standard <code>printf</code> conversions are accepted, with
- * the exception of `a`, `n`, and `p`. `e`, `f`, and `g`
- * conversions are accepted but equivalent to `f`. The `h` and `l`
- * length modifiers are accepted but ignored. No errors are
- * signalled for invalid format controls or insufficient
- * arguments.
+ * <p>The standard <a href="x-man-page://3/printf">Unix printf(3)</a> conversion specifications are accepted (with
+ * the exception of <code>a</code>, <code>n</code>, and <code>p</code>). <code>e</code>, <code>f</code>, and <code>g</code>
+ * conversions are accepted but equivalent to <code>f</code>.
+ * Positional arguments using the <code>$</code> field are
+ * supported. All the standard flags (<code>#</code> for alternate,
+ * <code>0</code> for zero padding, <code>-</code> for left
+ * justification, <code> </code> for sign alignment, <code>+</code>
+ * for explicit sign) are supported. The <code>'</code> flag
+ * (thousands separator) is ignored. Field width and precision are
+ * supported, including the use of parameterized (<code>*</code>)
+ * values.
+ * The <code>h</code> and <code>l</code>
+ * length modifiers are accepted but ignored.</p>
*
- * If the Debugger is present, There is an additional format
- * specifier `w` that formats the argument as if by `Debug.__String`
- * with the 'pretty'. If alternate format is requested (#), `w` uses the
- * full `Debug.__String` format used by <xref
- * linkend="LzDebugService+debug.prototype.write"/>. `%w` format obeys <xref
- * linkend="LzDebugService+debug.__ivars__.printLength"/>. If a precision is specified,
- * that is used as printLength.
+ * <p>No errors are
+ * signalled for invalid conversion directives.</p>
*
- * When used to format a Debugger message, any Object that is
- * formatted by `s` or `w` will create a link that can be clicked on
- * to inspect the object. There is an additional modifier for the
- * `w` format (=) which will take the next argument as the object to
- * be represented (i.e., linked to) by the formatted string; thus
- * permitting custom representations.
+ * <p>There is an additional conversion
+ * specifier <code>w</code> that formats the argument in a readable
+ * representation, similar to that of <xref
+ * linkend="LzDebugService+debug.prototype.write">Debug.write</xref>, but with less
+ * detail. If the alternate form is requested (with the <code>#</code> flag), <code>w</code> uses the
+ * full representation used by <xref
+ * linkend="LzDebugService+debug.prototype.write">Debug.write</xref>. The <code>%w</code> directive obeys <link
+ * linkend="LzDebugService+debug.__ivars__.printLength">Debug.printLength</link>. If a precision is specified,
+ * that is used as <code>Debug.printLength</code> for the
+ * corresponding conversion. If a representation is truncated
+ * because of precision for <code>w</code> or <code>#s</code> conversions, the abbreviation
+ * will be noted by ellipsis (…), rather than truncation. If the debugger is not present,
+ * <code>w</code> conversion behaves the same as <code>s</code>.</p>
*
+ * <p>Any Object that is
+ * represented by <code>s</code> or <code>w</code> conversions using the <code>Debug</code> formatted
+ * output methods will create a link that can be clicked on
+ * to inspect the represented object. There is an additional flag for the
+ * <code>s</code> and <code>w</code> formats (<code>=</code>) which will take the next argument as the object to
+ * be represented (i.e., linked to) by the conversion; thus
+ * permitting custom representations.</p>
+ *
* @param String control: A control string where % indicates a
- * subsequent argument is to be substituted.
+ * conversion directive that will be replaced by a representation of
+ * the corresponding argument as specified by the details of the
+ * conversion directive.
*
- * @param Array * args: arguments to be formatted according to the
+ * @param [*] args: arguments to be formatted according to the
* control string.
*
* @return LzMessage: the return value is an LzMessage which can be
@@ -184,6 +269,7 @@
var ctrl = '' + control;
// Zero-based
var argno = 0;
+ var maxarg = 0;
function getarg(i) {
if (i >= al) {
if ($debug) {
@@ -413,16 +499,17 @@
ctrl = ctrl.substring(start, limit);
base = 0, limit = ctrl.length;
start = 0, end = 0;
+ if (argno > maxarg) { maxarg = argno; }
}
- if (argno < al) {
+ if (maxarg < al) {
if ($debug) {
Debug.warn("%#0.48w: excess arguments", control);
}
// Output excess in 'write compatibility' mode
out.appendInternal(' ');
- for (; argno < al; argno++) {
- var arg = getarg(argno);
- var sep = ((argno == (al-1)) ? '\n' : ' ');
+ for (; maxarg < al; maxarg++) {
+ var arg = getarg(maxarg);
+ var sep = ((maxarg == (al-1)) ? '\n' : ' ');
out.append(arg);
out.appendInternal(sep);
}
Modified: openlaszlo/trunk/WEB-INF/lps/lfc/core/LzNode.lzs
===================================================================
--- openlaszlo/trunk/WEB-INF/lps/lfc/core/LzNode.lzs 2008-12-05 19:00:50 UTC (rev 11985)
+++ openlaszlo/trunk/WEB-INF/lps/lfc/core/LzNode.lzs 2008-12-05 19:01:36 UTC (rev 11986)
@@ -2222,6 +2222,7 @@
this.makeChild( dpobj , true);
}
+ /** @access private */
static var presentationtypes = {number: NumberPresentationType, numberExpression: NumberPresentationType, color: ColorPresentationType, inheritableBoolean: BooleanPresentationType, expression: ExpressionPresentationType, size: SizePresentationType}
// setting boolean: above freaks out rhino
presentationtypes['boolean'] = BooleanPresentationType;
Modified: openlaszlo/trunk/WEB-INF/lps/lfc/debugger/LzDebug.lzs
===================================================================
--- openlaszlo/trunk/WEB-INF/lps/lfc/debugger/LzDebug.lzs 2008-12-05 19:00:50 UTC (rev 11985)
+++ openlaszlo/trunk/WEB-INF/lps/lfc/debugger/LzDebug.lzs 2008-12-05 19:01:36 UTC (rev 11986)
@@ -48,7 +48,7 @@
* debug messages will also give a source location.</p>
*
* <p>The debug messages can be silenced by setting
- * <xref linkend="LzDebugService+debug.__ivars__.messageLevel"/>.</p>
+ * <link linkend="LzDebugService+debug.__ivars__.messageLevel">Debug.messageLevel</link>.</p>
*
* <p>Debugger messages are <em>inspectable</em>, as the example below
* demonstrates. Clicking on the printed representation of the
@@ -345,12 +345,12 @@
* an informative format. Simple objects are represented as
* themselves. Printed Complex objects are represented by their type
* and a concise description. Long representations (and long Strings)
- * are abbreviated if they are longer than <xref linkend="LzDebugService+debug.__ivars__.printLength"/>. Complex
+ * are abbreviated if they are longer than <link linkend="LzDebugService+debug.__ivars__.printLength">Debug.printLength</link>. Complex
* objects and abbreviated objects presented as links. Clicking on
* the link will invoke <xref linkend="LzDebugService+debug.prototype.inspect"/> on the object,
* giving more detail.
*
- * @param Array * any: One or more values to display. Multiple
+ * @param [*] any: One or more values to display. Multiple
* values are separated by spaces, so <code>Debug.write("The answer
* is:", 39+3)</code> will display: <code>The answer is: 42</code>
*/
@@ -369,10 +369,10 @@
* Formats its arguments using <xref
* linkend="LzFormatter.prototype.formatToString"/>.
*
- * @param String control: A control string where % indicates a
- * subsequent argument is to be substituted
+ * @param String control: A control string where % indicates the
+ * conversion of the corresponding argument
*
- * @param Array * args: Any number of arguments to be formatted
+ * @param [*] args: Any number of arguments to be formatted
* according to the control string
*/
function format (control:String, ...args) {
@@ -417,12 +417,12 @@
* Display a warning message on the console.
*
* Formats its arguments using <xref linkend="LzFormatter.prototype.formatToString"/>.
- * May be silenced by setting <xref linkend="LzDebugService+debug.__ivars__.messageLevel"/>.
+ * May be silenced by setting <link linkend="LzDebugService+debug.__ivars__.messageLevel">Debug.messageLevel</link>.
*
- * @param string control: A control string where % indicates a
- * subsequent argument is to be substituted
+ * @param string control: A control string where % indicates the
+ * conversion of the corresponding argument
*
- * @param Array * args: Any number of arguments to be formatted
+ * @param [*] args: Any number of arguments to be formatted
* according to the control string
*/
override function warn (...args) {
@@ -433,12 +433,12 @@
* Display an error message on the console.
*
* Formats its arguments using <xref linkend="LzFormatter.prototype.formatToString"/>.
- * May be silenced by setting <xref linkend="LzDebugService+debug.__ivars__.messageLevel"/>.
+ * May be silenced by setting <link linkend="LzDebugService+debug.__ivars__.messageLevel">Debug.messageLevel</link>.
*
- * @param string control: A control string where % indicates a
- * subsequent argument is to be substituted
+ * @param string control: A control string where % indicates the
+ * conversion of the corresponding argument
*
- * @param Array * args: Any number of arguments to be formatted
+ * @param [*] args: Any number of arguments to be formatted
* according to the control string
*/
override function error (...args) {
@@ -449,12 +449,12 @@
* Display an informational message on the console.
*
* Formats its arguments using <xref linkend="LzFormatter.prototype.formatToString"/>.
- * May be silenced by setting <xref linkend="LzDebugService+debug.__ivars__.messageLevel"/>.
+ * May be silenced by setting <link linkend="LzDebugService+debug.__ivars__.messageLevel">Debug.messageLevel</link>.
*
- * @param string control: A control string where % indicates a
- * subsequent argument is to be substituted
+ * @param string control: A control string where % indicates the
+ * conversion of the corresponding argument
*
- * @param Array * args: Any number of arguments to be formatted
+ * @param [*] args: Any number of arguments to be formatted
* according to the control string
*/
override function info (...args) {
@@ -465,12 +465,12 @@
* Display a debugging message on the console.
*
* Formats its arguments using <xref linkend="LzFormatter.prototype.formatToString"/>.
- * May be silenced by setting <xref linkend="LzDebugService+debug.__ivars__.messageLevel"/>.
+ * May be silenced by setting <link linkend="LzDebugService+debug.__ivars__.messageLevel">Debug.messageLevel</link>.
*
- * @param string control: A control string where % indicates a
- * subsequent argument is to be substituted
+ * @param string control: A control string where % indicates the
+ * conversion of the corresponding argument
*
- * @param Array * args: Any number of arguments to be formatted
+ * @param [*] args: Any number of arguments to be formatted
* according to the control string
*/
override function debug (...args) {
Modified: openlaszlo/trunk/WEB-INF/lps/lfc/debugger/LzMessage.lzs
===================================================================
--- openlaszlo/trunk/WEB-INF/lps/lfc/debugger/LzMessage.lzs 2008-12-05 19:00:50 UTC (rev 11985)
+++ openlaszlo/trunk/WEB-INF/lps/lfc/debugger/LzMessage.lzs 2008-12-05 19:01:36 UTC (rev 11986)
@@ -133,7 +133,7 @@
* message. Objects are recorded in a fashion that will enable the
* representation to be linked back to the object.
*
- * @param Array * args: the arguments to append to the initial message
+ * @param [*] args: the arguments to append to the initial message
*
* @access private
*/
@@ -317,7 +317,7 @@
* @param String file: filename or null
* @param Number line: line number or null
* @param String control: a format control string
- * @param Array * args: the arguments to the format control
+ * @param [*] args: the arguments to the format control
*
* @access private
*/
Modified: openlaszlo/trunk/WEB-INF/lps/lfc/debugger/LzMonitor.lzs
===================================================================
--- openlaszlo/trunk/WEB-INF/lps/lfc/debugger/LzMonitor.lzs 2008-12-05 19:00:50 UTC (rev 11985)
+++ openlaszlo/trunk/WEB-INF/lps/lfc/debugger/LzMonitor.lzs 2008-12-05 19:01:36 UTC (rev 11986)
@@ -31,7 +31,7 @@
/**
* Create a monitor message from a format string
* @param String control: a format control string
- * @param Array * args: the arguments to the format control
+ * @param [*] args: the arguments to the format control
*
* @see Debug.format
*
Modified: openlaszlo/trunk/WEB-INF/lps/lfc/debugger/LzTrace.lzs
===================================================================
--- openlaszlo/trunk/WEB-INF/lps/lfc/debugger/LzTrace.lzs 2008-12-05 19:00:50 UTC (rev 11985)
+++ openlaszlo/trunk/WEB-INF/lps/lfc/debugger/LzTrace.lzs 2008-12-05 19:01:36 UTC (rev 11986)
@@ -32,7 +32,7 @@
/**
* Create a trace message from a format string
* @param String control: a format control string
- * @param Array * args: the arguments to the format control
+ * @param [*] args: the arguments to the format control
*
* See also: Debug.format
*
Modified: openlaszlo/trunk/WEB-INF/lps/lfc/views/LzText.lzs
===================================================================
--- openlaszlo/trunk/WEB-INF/lps/lfc/views/LzText.lzs 2008-12-05 19:00:50 UTC (rev 11985)
+++ openlaszlo/trunk/WEB-INF/lps/lfc/views/LzText.lzs 2008-12-05 19:01:36 UTC (rev 11986)
@@ -433,6 +433,7 @@
}
};
+/** @access private */
static var fontArgToAttr:Object = {font: 'fontname', fontsize: 'fontsize', fontstyle: 'fontstyle'};
@@ -914,10 +915,10 @@
* linkend="LzFormatter.prototype.formatToString"/> and sets the text of the
* view to the result.
*
- * @param String control: A control string where % indicates a
- * subsequent argument is to be substituted
+ * @param string control: A control string where % indicates the
+ * conversion of the corresponding argument
*
- * @param Array * args: arguments to be formatted according to the
+ * @param [*] args: arguments to be formatted according to the
* control string
*/
function format (control:String, ...args) {
Modified: openlaszlo/trunk/lps/components/debugger/library.lzx
===================================================================
--- openlaszlo/trunk/lps/components/debugger/library.lzx 2008-12-05 19:00:50 UTC (rev 11985)
+++ openlaszlo/trunk/lps/components/debugger/library.lzx 2008-12-05 19:01:36 UTC (rev 11986)
@@ -6,7 +6,7 @@
@access public
@topic LZX
@subtopic Debugging
- @devnote NOTE [2008-11-25 ptw] Dummy class to hold documentation for <debug> tag
+ @devnote NOTE [2008-11-25 ptw] Dummy class to hold documentation for debug tag
@devnote TODO [2008-11-26 ptw] Make this the real class!
-->
<class name="debug">
@@ -14,14 +14,17 @@
<tag name="shortdesc"><text>Controlling the Laszlo debugger console window</text></tag>
<tag name="lzxname"><text>debug</text></tag>
<text>
- <p>The optional <code>debug</code> tag controls the appearance of
- the debugger console when debugging is on. It does <em>not</em>
- cause the application to be compiled with debugging mode enabled.
- By default, the debug console will appear as a <code>view</code> in
- the application canvas, sized to fit the lower 1/2 of the canvas.
- The usual <code>view</code> attributes can be used to size and
+ <p>For runtimes that use a view on the application canvas as the debugger console window,
+ the optional <code><debug /></code> tag controls the appearance
+ of window.
+ The <code><debug /></code> tag does <em>not</em>
+ cause the application to be compiled with debugging mode enabled.</p>
+ <p>
+ When applicable, by default, the debug console will appear as a <code>view</code>
+ sized to fit the lower 1/2 of the canvas.
+ The usual <code>view</code> attributes can be used to override these defaults to size and
position the debug console window. If you need to programmatically
- control the debug console window, use the <code>name</code>
+ control the debugger console window, use the <code>name</code>
attribute:</p>
<example class="program" id="debug-1" title="Controlling the Debug console window">
@@ -40,9 +43,10 @@
]]>
</example>
- <p>Note the conditionalization testing whether the named window
- exists or not. The <code>debug</code> tag will <em>not</em> create
- a window in the application canvas if remote or console debugging
+ <p>Note the test to verify that the window exists before we try to manipulate it.
+ The <code><debug /></code> tag will <em>not</em> create
+ a window in the application canvas for runtimes or IDE's that have an external debugger console,
+ or if remote or developer console debugging
is enabled.</p>
</text>
</doc>
More information about the Laszlo-checkins
mailing list