This is a two-stage process. The first stage is to run the help() command in the Foldit client. The help() command with no arguments produces a list of all functions in the Foldit Lua interface. The second stage is to run a help command for each function name listed in the first stage.
The resulting output can then be formatted into wiki markup.
The same general process applies for both version 1 and version 2 of the Foldit Lua interface. The options needed for version 1 are listed in bold.
The steps involved are:
Obtain help() output[edit | edit source]
- Run the help() command with no arguments in the Foldit client. This produces a list of function names in the client's scriptlog.
- Version 1: the output of the help() command is different for version 1 and version 2. You must use a version 1 recipe to produce the list of version 1 functions. There's no way to create a new version 1 recipe in Foldit, however. The recipe V1 help command exists for this purpose.
- The help() output looks like this:
void print([arg1,...,argN]) boolean absolutebest.AreConditionsMet() number absolutebest.GetEnergyScore() number absolutebest.GetExplorationMultiplier() ...and so on...
- Double-check the help() output.
In the version 2 output, there have been various problems, such as missing parentheses, for some of the functions. See the feedback problems with help() output for details. Many of the longstanding problems were corrected in October 2020.
- Version 1: the help() output does not require any corrections.
Generate the detailed help commands[edit | edit source]
- Using the Lua program "LuaHelp2Help", or a similar tool, transform the help() output into this format:
help ( print ) help ( absolutebest.AreConditionsMet ) help ( absolutebest.GetEnergyScore ) help ( absolutebest.GetExplorationMultiplier ) ...and so on...
- The transformed help () output should have one help command per function name.
- Run the transformed help() output as a script in the Foldit client.
- The new script log output should have two lines per function name:
void print([arg1,...,argN])</nowiki> Print values to the output window and log file. boolean absolutebest.AreConditionsMet() Return whether the absolute best pose satisfies all conditions. number absolutebest.GetEnergyScore() Get the score for the absolute best pose. number absolutebest.GetExplorationMultiplier() Get the Exploration multiplier. If the current puzzle is not an exploration puzzle, returns 0. ...and so on...
- Each function has two lines in the output. The first line is the function's signature as before, and the second line is a brief description of the function.
- Again, double-check the results for version 2. Issues with missing parentheses and duplicated function names have mostly been cleared up.
- Version 1: the output does not require any corrections.
Generate the wiki page markup[edit | edit source]
Using the program "LuaFunctions" or a similar tool, the detailed help() output can be transformed into the wiki markup for the Foldit Lua Functions page. u The output from "LuaFunctions" can be used to replace the wiki page.
The programs LuaHelp2Help and LuaFunctions have been shared as Foldit scripts. If run in the Foldit client, they produce a message explaining that they are standalone programs, and not regular Foldit scripts.
These two programs are intended to be run in a Lua command-line environment. The Lua for Windows package was used to create these programs.
Both programs ignore XML tags, so they can be run using a Foldit script log as their input.
LuaHelp2Help is a simple reformatting of the "help()" output.
LuaFunctions is more complex. Internally, it includes a list of V1 equivalents of the V2 functions, and a description of each function namespace, such as "absolutebest", "structure", and "band". The program also has a list of functions which the author believes are not implemented.
Version 1: LuaFunctions now includes a list of V2 equivalents of the V1 functions.
Detailed procedure[edit | edit source]
The following procedure was used to update the wiki page on 21 November, 2020.
Version 1: the options required for generating the version 1 functions wiki page appear in bold.
These steps were performed in a Windows environment with the "Lua for Windows" package installed. The "lua" command at a Windows command prompt invokes the Lua interpreter.
In the examples below, most of the quoted strings are for clarity and emphasis. In most cases, these quoted strings should be retyped without quotes. One exception is when a file name containing spaces is used as a command-line argument, in which case the quotes are required.
The same steps need to be repeated for both version 1 and version 2. Use "v1" and "v2" in the output file names to keep the two versions separate.
- Create a work directory (folder) for the files. Create a new directory each time an update is required, using the release number as part of the directory name. For example, "20201118-a5da4dfdf5-win_x86-devprev" is the current devprev release. The current release is available via the "General Options" button on the "Menu" menu. The "Copy" button of general options copies the release id string to the clipboard. The directory name might be something like:
- In the Foldit client, download the current version of the two standalone Lua scripts:
Lua Help2Help 1.0 -- http://fold.it/portal/recipe/101069 LuaFunctions1.4 -- http://fold.it/portal/recipe/102310
- In the Foldit recipe editor, use "Save As" then "Export" to save "Lua Help2Help" and "Lua Functions" to the work directory. The names "Lua Help2Help 1.0.lua" and "LuaFunctions1.4.lua" are used here, but names without spaces may be used.
- In the Foldit client, create a track called "help". Recipe output will go to "scriptlog.help.xml". Tracks are created via the "Tracks" button of the "Undo" menu.
- In the Foldit recipe editor, click "New (ScriptV2)". Enter the command "help()" in the editor window. Click "Run".
- Version 1: use the recipe V1 help command to generate the first stage output.
- Copy "scriptlog.help.xml" to the work directory and edit it with the editor of your choice.
- Locate the function "metric.GetBonus". Add a left parenthesis between "GetBonus" and "string" so the line reads:
number metric.GetBonus(string name)
- Version 1: no manual edits required.
- Save the modified "scriptlog.help.xml". (It's not necessary to remove the XML tags.)
- At a command prompt in the work directory, enter the command (note that the quotes are required here):
lua "Lua Help2Help 1.0.lua" scriptlog.help.xml >LuaHelp2Help.v2.out.txt
- Version 1: use "v1" in the output filename:
lua "Lua Help2Help 1.0.lua" scriptlog.help.xml >LuaHelp2Help.v1.out.txt
- Edit "LuaHelp2Help.v2.out.txt" and copy all lines to the clipboard. (Check that the last line says "0 invalid lines".)
- Version 1: edit "LuaHelp2Help.v1.out.txt" and copy all lines to the clipboard.
- In the Foldit client, create a new track called "Help2Help". Recipe output will go to "scriptlog.Help2Help.xml".
- In the Foldit recipe editor, click "New (ScriptV2)" and paste in the lines from copied from "LuaHelp2Help.out.v2.txt". (Alternately, use "Load", "Import' to load "LuaHelp2Help.out.v2.txt".) Click "Run" to run the recipe.
- Version 1: you'll need an version 1 recipe. You can save V1 help command under a new name, and then paste in the new commands from "LuaHelp2Help.v1.out.txt". Then click "Run" to run the recipe.
- Copy "scriptlog.Help2Help.xml" to the work directory and edit it.
- As in a previous step, update "scriptlog.Help2Help.xml" to add a left parenthesis after "metric.GetBonus".
- Version 1: no manual edits required.
- At a command prompt in the work directory, enter the command:
lua "LuaFunctions1.4.lua" scriptlog.Help2Help.xml LuaFunctions.out.v2.txt 20201118-a5da4dfdf5-win_x86-devprev
- Version 1: add "V1" at the end of the command line:
lua "LuaFunctions1.4.lua" scriptlog.Help2Help.xml LuaFunctions.out.v1.txt 20201118-a5da4dfdf5-win_x86-devprev V1
- Edit "LuaFunctions.out.v2.txt" and copy all lines to the clipboard.
- Version 1: edit "LuaFunctions.out.v1.txt" and copy all lines to the clipboard.
- On the wiki page Foldit Lua Functions, click the down arrow next to "Edit" then "Classic Editor" from the dropdown. In the classic editor, select the "Source" tab. Delete all the existing text and paste in the contents of "LuaFunctions.out.txt". Use the "Preview" button to preview the page, then click "Publish" if the results look OK.
- Version 1: update Foldit Lua Functions (v1) with the contents of LuaFunctions.out.v1.txt
- A file called "details.txt" is also generated for both V1 and V2. It contains the wiki markup for the function detail pages. This markup can be used to start a new function detail page when functions have been added in a release.