From f628d5e8592b774132565ab153a8464c8d83548b Mon Sep 17 00:00:00 2001
From: wm4 <wm4@nowhere>
Date: Mon, 24 Feb 2014 20:47:20 +0100
Subject: lua: add a bunch of functions to get/set properties by their native
 type

There are some complications because the client API distinguishes
between integers and floats, while Lua has only "numbers" (which are
usually floats). But I think this should work now.
---
 DOCS/man/en/lua.rst | 42 ++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 40 insertions(+), 2 deletions(-)

(limited to 'DOCS')

diff --git a/DOCS/man/en/lua.rst b/DOCS/man/en/lua.rst
index 93a169a391..b84984e6ce 100644
--- a/DOCS/man/en/lua.rst
+++ b/DOCS/man/en/lua.rst
@@ -93,12 +93,50 @@ The ``mp`` module is preloaded, although it can be loaded manually with
     missing. Unlike ``get_property()``, assigning the return value to a variable
     will always result in a string.
 
+``mp.get_property_bool(name [,def])``
+    Similar to ``mp.get_property``, but return the property value as boolean.
+
+    Returns a boolean on success, or ``def, error`` on error.
+
+``mp.get_property_number(name [,def])``
+    Similar to ``mp.get_property``, but return the property value as number.
+
+    Note that while Lua does not distinguish between integers and floats,
+    mpv internals do. This function simply request a double float from mpv,
+    and mpv will usually convert integer property values to float.
+
+    Returns a number on success, or ``def, error`` on error.
+
+``mp.get_property_native(name [,def])``
+    Similar to ``mp.get_property``, but return the property value using the best
+    Lua type for the property. Most time, this will return a string, boolean,
+    or number. Some properties (for example ``chapter-list``) are returned as
+    tables.
+
+    Returns a value on success, or ``def, error`` on error. Note that ``nil``
+    might be a possible, valid value too in some corner cases.
+
+    (There is no ``mp.set_property_native`` yet.)
+
 ``mp.set_property(name, value)``
-    Set the given property to the given value. See ``mp.get_property`` and
-    `Properties`_ for more information about properties.
+    Set the given property to the given string value. See ``mp.get_property``
+    and `Properties`_ for more information about properties.
 
     Returns true on success, or ``nil, error`` on error.
 
+``mp.set_property_bool(name, value)``
+    Similar to ``mp.set_property``, but set the given property to the given
+    boolean value.
+
+``mp.set_property_number(name, value)``
+    Similar to ``mp.set_property``, but set the given property to the given
+    numeric value.
+
+    Note that while Lua does not distinguish between integers and floats,
+    mpv internals do. This function will test whether the number can be
+    represented as integer, and if so, it will pass an integer value to mpv,
+    otherwise a double float.
+
 ``mp.get_time()``
     Return the current mpv internal time in seconds as a number. This is
     basically the system time, with an arbitrary offset.
-- 
cgit v1.2.3