Merge pull request finale-lua#627 from rpatters1/RGP-changes-rgplua-0.70

Rgp changes rgplua 0.70

README.md

@@ -15,18 +15,23 @@
 
 ---
 
-RGP Lua and JW Lua allow you to create plugins for Finale. This repo will allow you to easily create and share Lua plugins with other Finale users. For developers, this repo even includes a standard library with common functions, drastically improving development time.
+RGP Lua and JW Lua allow you to create plugins for Finale. This repo will allow you easily to create and share Lua plugins with other Finale users. For developers, this repo even includes a standard library with common functions, drastically improving development time.
 
 Table of Contents:
 
 1. [Usage](#usage)
-2. [Contribute](#contribute)
+2. [Samples](#samples)
+3. [Contribute](#contribute)
    1. [Become a collaborator](#become-a-collaborator)
-3. [License](#license)
+4. [License](#license)
 
 ## Usage
 
-To use these scripts, the current best way is to download the entire repository, then add your desired scripts to RGP Lua or JW Lua. See https://youtu.be/EFGNuGCEIq4.
+To use these scripts, you can download the entire repository, then add your desired scripts to RGP Lua or JW Lua. See https://youtu.be/EFGNuGCEIq4 (JW Lua) or https://youtu.be/ju99glhwsMs (RGP Lua). Alternatively, you can use the [Finale Lua site](https://www.finalelua.com/).
+
+## Samples
+
+In addition to the working scripts in the [`src`](src/) directory, you can find script samples in the [`samples`](samples/) directory that illustrate how to use various features of the Finale Lua environment.
 
 ## Contribute
 

docs/rgp-lua.md

@@ -36,7 +36,7 @@ Both _RGP Lua_ and _JW Lua_ map the Lua script language to the [PDK Framework](h
 
 All accessible PDK Framework classes starts with the `FC` prefix, such as [`FCMeasure`](https://pdk.finalelua.com/class_f_c_measure.html), [`FCMusicRegion`](https://pdk.finalelua.com/class_f_c_music_region.html), [`FCNoteEntry`](https://pdk.finalelua.com/class_f_c_note_entry.html), etc.
 
-The methods names (and as a result, the Lua properties) in the PDK Framework are in _CamelCase_. The constants are all-uppercase.
+The methods names (and as a result, the Lua properties) in the PDK Framework are in [_UpperCamelCase_](https://en.wikipedia.org/wiki/Camel_case) (sometimes called "Pascal case"). The constants are all-uppercase.
 
 The Lua Language
 ----------------
@@ -547,13 +547,14 @@ The Lua language handles memory through garbage collection, so allocated memory
 * The memory allocated by the PDK Framework's `Create` methods is handled automatically in different ways by _RGP Lua_ and _JW Lua_. _JW Lua_ releases these memory objects _after_ the full script has been run. _RGP Lua_ allows the Lua engine to release them as part of normal Lua garbage collection.
 * For _JW Lua_, the `Create` methods can sometimes result in a huge number of objects waiting for release, for example, in a tight loop. `Lookup` classes (classes that end with `Lookup`) are available as a faster and more memory-efficient approach.
 * For _RGP Lua_, calling `Create` methods in tight loops is less of an issue, since Lua garbage collection releases unused items as the loop progresses. However the same `Lookup` classes are supported as in _JW Lua_.
-* When using the `FCCellMetrics` or `FCNoteEntryMetrics` class, make sure to call the `FreeMetrics()` method separately for the loaded object as soon as the data is no longer is needed. Finale allocates loaded metrics data internally, and metrics with a garbage collector can otherwise impact performance in scripts where lots of metrics data are loaded without release. This is not as big of an issue in _RGP Lua_ because Lua garbage collection also releases the internal metrics data, but `FreeMetrics()` still gives you the control to free it as soon as you no longer need it.
+* When using the `FCCellMetrics` or `FCEntryMetrics` class, make sure to call the `FreeMetrics()` method separately for the loaded object as soon as the data is no longer is needed. Finale allocates loaded metrics data internally, and metrics with a garbage collector can otherwise impact performance in scripts where lots of metrics data are loaded without release. This is not as big of an issue in _RGP Lua_ because Lua garbage collection also releases the internal metrics data, but `FreeMetrics()` still gives you the control to free it as soon as you no longer need it. Metrics also allow the `<close>` keyword in Lua 5.4, which calls `FreeMetrics()` automatically when the variable goes out of scope.
 
 Tips
 ----
 
 * If you don't need a collection object anymore, you can set it to `nil`. That might benefit the performance in large scripts with huge collections of data (since it signals to the garbage collector that it can free the allocated memory).
-* There's virtually no performance penalty to put lots of comments in the script code. Once the script has been loaded into the Lua engine, the code resides in (quite efficient) bytecode where only the actual execution code appears.
+* _RGP Lua_ uses Lua 5.4, which includes the `<close>` keyword. Most of the collection classes in the PDK Framework support `<close>`. (See the [documentation](https://pdk.finalelua.com).) If you define your collection instances with `<close>`, they free their memory as soon as they go out of scope.
+* There is virtually no performance penalty to put lots of comments in the script code. Once the script has been loaded into the Lua engine, the code resides in (quite efficient) bytecode where only the actual execution code appears.
 * An alternative syntax for properties is to use the property name as a string table index with the object as a table. For example, the syntax `mymeasure.Width` is equivalent to `mymeasure["Width"]`. This alternative syntax might be useful when referencing properties dynamically through the code, especially in string variables. Example:
 
 ```lua

docs/rgp-lua/finaleplugin-properties.md

@@ -150,6 +150,18 @@ Default is `false`.
 
 ---
 
+#### HashURL\* (string)
+
+If this property is present, _RGP Lua_ will attempt to hash-verify the script. As long as it has not been modified, a hash-verified script runs in trusted mode. The website specified in the URL must be a trusted website on a whitelist maintained by the Finale Lua organization at GitHub. The URL should point to a text file in the following format:
+
+```
+<sha-512 hash> <file name>
+```
+
+_RGP Lua_ computes the hash on the local copy of the script and compares it to the hash specified in the file at the URL. The file names must also match. As of v0.70, file names may contain spaces. Note that line endings affect the hash, so the line endings must be the same on both the server copy and the local copy of the script. If either the hash code or file name does not match, _RGP Lua_ still runs the script in untrusted mode. You can force an error instead by setting the "Error on Hash Mismatch" opton in the [configuration dialog](/docs/rgp-lua/rgp-lua-configuration).
+
+---
+
 #### IgnoreReturnValue\* (boolean)
 
 _RGP Lua_ displays to the user any non-nil value returned by a script, regardless of whether an error occurred. You can suppress this display when there is no error by setting this value to `true`. Example:

docs/rgp-lua/finenv-properties.md

@@ -146,6 +146,28 @@ end
 
 ---
 
+#### GetFinaleMainWindow\* (function)
+
+Returns an opaque handle to the main Finale window (Windows) or `nil` (macOS). This can be used to pass to functions in `luaosutils.menu` for manipulating Finale's menus. To Lua it looks like light userdata.
+
+```lua
+local menu = require("luaosutils").menu
+local finale_menu = menu.get_top_level_menu(finenv.GetFinaleMainWindow())
+```
+
+---
+
+#### GetPluginDefFunction\* (function)
+
+Returns a string containing the `plugindef` function that _RGP Lua_ parsed out of the script file. You can use this for diagnostic purposes if you think your `plugindef` function is not being parsed correctly.
+
+```lua
+local parsed_plugindef = finenv.GetPluginDefFunction()
+-- You can now inspect parsed_plugindef to see what RGP Lua parsed from your script.
+```
+
+---
+
 #### IsFinaleDemo\* (read-only property)
 
 Returns `true` if the version of Finale that is currently running is the demo version that cannot save or print. (Available starting in version 0.67 of _RGP Lua_.)
@@ -194,9 +216,20 @@ Returns a string with the current version of LuaBridge that is embedded in _RGP
 
 ---
 
-#### MajorVersion & MinorVersion (read-only properties)
+#### LuaReleaseVersion\* (read-only property)
+
+Returns a string containing the full release version of the embedded Lua, including the minor update version.
 
-Return the major and minor version numbers, respectively, of the running Lua plugin. (Either _RGP Lua_ or _JW Lua_.)
+```lua
+print(finenv.LuaReleaseVersion)
+-- prints "Lua 5.4.6" or whatever the current value is
+```
+
+---
+
+#### MajorVersion (read-only property)
+
+Return the major version number of the running Lua plugin. (Either _RGP Lua_ or _JW Lua_.)
 
 Example:
 
@@ -235,6 +268,20 @@ end
 
 ---
 
+#### MinorVersion (read-only property)
+
+Returns the minor version number of the running Lua plugin. (Either _RGP Lua_ or _JW Lua_.)
+
+Example:
+
+```lua
+if finenv.MajorVersion > 0 or finenv.MinorVersion > 54 then
+   -- RGP Lua v0.55+ feature implemented here
+end
+```
+
+---
+
 #### QueryInitializationInProgress\* (function)
 
 A function that returns `true` if the script is currently running at Finale startup. You can request your script to run at startup with `finaleplugin.ExecuteAtStartup = true` in your `plugindef` function.

docs/rgp-lua/rgp-lua-classbrowser.md

@@ -1,23 +1,45 @@
 RGP Lua Class Browser
 =====================
 
-The RGP Lua Class Browser is a re-implementation in pure Lua of the Class Browser in _JW Lua_. It displays the available classes from embedded C++ frameworks, along with their methods and properties. As of version 0.68 of _RGP Lua_, the embedded C++ frameworks are:
+The RGP Lua Class Browser is a re-implementation in pure Lua of the Class Browser in _JW Lua_. It displays the available classes from embedded C++ frameworks, along with their methods and properties. As of version 0.70 of _RGP Lua_, the embedded C++ frameworks are:
 
-- `finale` : the classes in the [PDK Framework](https://pdk.finalelua.com/) for Finale.
-- `tinyxml2` : the classes in the [tinyxml2](/docs/rgp-lua/tinyxml2) library.
+- `finale` : the classes and constants in the [PDK Framework](https://pdk.finalelua.com/) for Finale.
+- `finenv` : the methods and properties in the [finenv](https://www.finalelua.com/docs/rgp-lua/finenv-properties) namespace.
+- `tinyxml2` : the classes and constants in the [tinyxml2](/docs/rgp-lua/tinyxml2) library.
 
 The Class Browser is included as `rgpluaclassbrowser.lua` in the zip archive of RGP Lua Utilities available on the [download page](https://robertgpatterson.com/-fininfo/-rgplua/rgplua.html) for RGP Lua.
 
-The `rgpluaclassbrowser.lua ` script requires version 0.56 or higher of _RGP Lua_. It also requires the `jwluatagfile.xml` from the zip file. Other than that it has no dependencies. You may place the two files together anywhere on your hard drive. Once you have [configured](/docs/rgp-lua/ the `.lua` file in RGP Lua, it will be available to run.
+The `rgpluaclassbrowser.lua ` script requires version 0.56 or higher of _RGP Lua_. It also requires the `jwluatagfile.xml` from the zip file. Other than that it has no dependencies. You may place the two files together anywhere on your hard drive. Once you have [configured](/docs/rgp-lua/rgp-lua-configuration) the `.lua` file in RGP Lua, it will be available to run.
 
 ![RGP Lua Class Browser](assets/rgpluaclassbrowser.jpg "RGP Lua Class Browser")
 
 The edit boxes across the top allow you to filter classes, properties, and methods. The filter is case-insensitive and finds the filter text anywhere in the name. In the example you can see that a filter of "note" has found every class whose name includes the word "note", ignoring case.
 
+Starting with _RGP Lua v.70_, the class browser shows deprecation status and first available version for methods and properties. These are based on the [PDK Framework](https://pdk.finalelua.com) documentation and are only as accurate as the documentation is. However, every effort is made to keep the documentation correct and current.
+
 **Class Documentation** This button launches a browser to the page for the class on the [PDK Framework](https://pdk.finalelua.com/) website.
 
 **Doc.** The `Doc.` buttons launch a browser to the specific method page that is selected in their respective columns. The `Doc.` button for properties launches the page for the property getter method.
 
+**Copy** The `Copy` button copies the currently selected item to the clipboard. Items in the `Classes	` column are prepended with the namespace. Items in the `Class Methods` column are prepended with namespace and class name. The goal is to be able to insert them directly into a script without any additional typing. You can also use `cmd+C` (macOS) or `ctrl-C` (Windows) instead of pressing this button.
+
+**Double clicking** an item or pressing the **Enter Key** while an item is selected brings up the [Details](#details-dialog) dialog box for that item.
+
+
+---
+
+### Keyboard commands
+
+---
+
+The list boxes in the Class Browser respond to the standard OS keystrokes for navigation: up arrow, down arrow, home, end, etc. You can also type an initial letter and it jumps to the first item starting with that letter.
+
+In addition, the Class Browser list boxes respond to the following keystrokes:
+
+- **Copy**:  `cmd+C` (macOS) `ctrl+C` (Windows)
+- **Select Item**: `Enter` (brings up the [Details](#details-dialog) dialog box.)
+
+
 ---
 
 ### The 'jwluatagfile.xml' File
@@ -27,3 +49,24 @@ The edit boxes across the top allow you to filter classes, properties, and metho
 You can run the any version of RGP Lua Class Browser with any version of _RGP Lua_ from 0.56 on. However, for best results you should always run with the latest version of `jwluatagfile.xml`. It is the version that matches the links on the [PDK Framework](https://pdk.finalelua.com/) website.
 
 The latest version (and the version that matches the PDK website) is always available at the [download site](https://robertgpatterson.com/-fininfo/-rgplua/rgplua.html) in the RGP Lua Utilities zip file link.
+
+
+---
+
+### Details Dialog
+
+---
+
+The Details Dialog appears when you select an item in one of the list boxes, either with the `Enter` key or by double clicking. It shows the same information as the column under the list box, but it is wide enough to show the complete information for argument lists and return types.
+
+
+![Item Details](assets/rgpluaclassbrowser_details.jpg "Item Details")
+
+The editable text field is initialized with the same value that the Copy button would copy to the clipboard. You can edit it to anything you wish and then copy it from there.
+
+The rest of the dialog shows static information about the class or method. This information is gathered from the `jwluatagfile.xml` file as well as internal metadata that _RGP Lua_ provides to the Lua environment. In particular, _RGP Lua_ (starting with v0.70) provides the following metadata about each method or property directly:
+
+- deprecation status
+- first available _RGP Lua_ version or blank if it was available in _JW Lua_
+
+These values are manually maintained based on the [PDK Framework](https://pdk.finalelua.com/) documentation. Every effort is made to keep them current and accurate, but they should be treated as information only. Do not use these to control program flow as there are more reliable approaches to determine the availability of a particular method or property inside your scripts. (The most straightforward is checking it for `nil`.)