Code
--[[
LuaFunctions
This script generates wikia markup for the Foldit Lua functions,
both version 1 and version 2.
The input to this script is the output of the help command for each function.
The list of functions is generated by running the command:
help ()
in the Foldit client. This list can be converted into another Foldit script,
a series of commands in the form:
help ( functionname )
Each help command in this form returns two lines.
The first line contains the function return value(s), name, and parameters.
The second line contains a description of the function.
For example, the Foldit Lua command:
help ( behavior.SegClashingImportance )
returns these two lines:
void behavior.SetClashImportance(number importance)
Set the clashing importance. (Range 0.0 to 1.0)
This script converts the detailed output into wikia markup.
The markup includes HTML tags, which gives better control over
the final format. For example, the H1 tag is used to group functions
by name space.
The script makes a few adjustments for version 1 functions,
such as adding different abstract and using a different
wiki template.
This is a command line LUA program. The command line syntax is:
lua LuaFunctions1.4.lua helpfile wikifile [releaseid] [V1]
helpfile is the long-form output of the help command for each function
wikifile is the output wikia markup file
releaseid is the optional Foldit release id
V1 is optional flag for version 1, must be literal "V1"
The output of the foldit help command may contain errors, such as the line
void structure.TweakRotateinteger segmentIndex, number angle)
found in the current foldit release, which is missing the opening "(".
Consider fixing this error before running LuaFunctions.
revision history
----------------
version 1.0 -- 2015/06/04 -- LociOiling
+ new function
version 1.1 -- 2016/05/10 -- LociOiling
+ fix typo
version 1.2 -- 2017/03/18 -- LociOiling
+ adapt to handle v1 functions
version 1.3 -- 2018/03/08 -- LociOiling
+ fix typo (never released)
version 1.4 -- 2020/11/20 -- LociOiling
+ add bold to the auto-generated text warning
+ include graphic
+ make V1-V2 names links
+ use named table values internally
+ generate macros for detail pages,
write to "details.txt" (fixed name)
+ minor cleanup
]]--
function main ()
local Recipe = "Lua Functions"
local Version = "1.4"
local ReVersion = Recipe .. " v" .. Version
--
-- history table -- list V1 versions of functions, some other infomation
--
-- for V1 functions, the keyword starts with underscore
--
-- for both V1 and V2, the value should a function name,
-- optionally prefixed by "similar to"
--
-- the values are converted to links using the somewhat clunky
-- wiki page naming convention for Foldit Lua functions
--
local histtabl =
{
_print = "print",
absolutebest_Restore = "restore_abs_best",
band_AddBetweenSegments = "band_add_segment_segment",
band_Delete = "band_delete",
band_DeleteAll = "band_delete",
band_Disable = "similar to band_disable",
band_DisableAll = "band_disable",
band_Enable = "similar to band_enable",
band_EnableAll = "band_enable",
band_GetCount = "get_band_count",
band_SetGoalLength = "band_set_length",
band_SetStrength = "band_set_strength",
behavior_SetClashImportance = "set_behavior_clash_importance",
creditbest_Restore = "restore_credit_best",
current_AreConditionsMet = "are_conditions_met",
current_GetExplorationMultiplier = "get_exploration_score",
current_GetScore = "get_ranked_score(true)",
current_GetSegmentEnergyScore = "similar to get_segment_score",
current_GetSegmentEnergySubscore = "similar to get_segment_score_part",
freeze_FreezeSelected = "do_freeze",
freeze_UnfreezeAll = "do_unfreeze_all",
puzzle_StartOver = "reset_puzzle",
recentbest_Restore = "restore_recent_best",
recentbest_Save = "reset_recent_best",
rotamer_GetCount = "get_sidechain_snap_count",
rotamer_SetRotamer = "do_sidechain_snap",
save_LoadSecondaryStructure = "load_structure",
save_Quickload = "quickload",
save_Quicksave = "quicksave",
save_SaveSecondaryStructure = "save_structure",
selection_Deselect = "similar to deselect_index",
selection_DeselectAll = "deselect_all",
selection_Select = "similar to select_index",
selection_SelectAll = "select_all",
selection_SelectRange = "select_index_range",
structure_GetAminoAcid = "similar to get_aa",
structure_GetCount = "get_segment_count",
structure_GetDistance = "get_segment_distance",
structure_GetSecondaryStructure = "similar to get_ss",
structure_IsHydrophobic = "similar to is_hydrophobic",
structure_LocalWiggleSelected = "similar to do_local_wiggle",
structure_MutateSidechainsSelected = "similar to do_mutate",
structure_RebuildSelected = "do_local_rebuild",
structure_SetAminoAcidSelected = "replace_aa",
structure_SetSecondaryStructureSelected = "replace_ss",
structure_ShakeSidechainsSelected = "similar to do_shake",
structure_WiggleSelected = "similar to do_global_wiggle_all",
ui_GetPlatform = "get_platform",
_are_conditions_met = "current.AreConditionsMet",
_band_add_segment_segment = "band.AddBetweenSegments",
_band_delete = "band.Delete",
_band_disable = "band.Disable",
_band_enable = "band.Enable",
_band_set_length = "band.SetGoalLength",
_band_set_strength = "band.SetStrength",
_deselect_all = "selection.DeselectAll",
_deselect_index = "similar to selection.Deselect",
_do_freeze = "similar to freeze.FreezeSelected ",
_do_global_wiggle_all = "similar to structure.WiggleSelected",
_do_global_wiggle_backbone = "similar to structure.WiggleSelected",
_do_global_wiggle_sidechains = "similar to structure.WiggleSelected",
_do_local_rebuild = "structure.RebuildSelected",
_do_local_wiggle = "structure.LocalWiggleSelected",
_do_mutate = "structure.MutateSidechainsSelected",
_do_shake = "structure.ShakeSidechainsSelected",
_do_sidechain_snap = "rotamer.SetRotamer",
_do_unfreeze_all = "freeze.UnfreezeAll",
_get_aa = "structure.GetAminoAcid",
_get_band_count = "band.GetCount",
_get_exploration_score = "current.GetExplorationMultiplier",
_get_platform = "ui.GetPlatform",
_get_ranked_score = "current.GetScore",
_get_score = "current.GetScore",
_get_segment_count = "structure.GetCount",
_get_segment_distance = "structure.GetDistance",
_get_segment_score = "current.GetSegmentEnergyScore",
_get_segment_score_part = "current.GetSegmentEnergySubscore",
_get_sidechain_snap_count = "rotamer.GetCount",
_get_ss = "structure.GetSecondaryStructure",
_is_hydrophobic = "structure.IsHydrophobic",
_load_structure = "save.LoadSecondaryStructure",
_quickload = "save.Quickload",
_quicksave = "save.Quicksave",
_replace_aa = "structure.SetAminoAcidSelected",
_replace_ss = "structure.SetSecondaryStructure",
_reset_puzzle = "puzzle.StartOver",
_reset_recent_best = "recentbest.Restore",
_restore_abs_best = "absolutebest.Restore",
_restore_credit_best = "creditbest.Restore",
_restore_recent_best = "recentbest.Restore",
_save_structure = "save.SaveSecondaryStructure",
_select_all = "selection.SelectAll",
_select_index = "similar to selection.Select",
_select_index_range = "selection.SelectRange",
_set_behavior_clash_importance = "behavior.SetClashImportance",
}
--
-- nametabl describes the foldit namespaces
--
local nametabl =
{
no_namespace = "The \"no namespace\" functions are general utilities.",
absolutebest = "The absolutebest functions work with the highest-scoring pose, regardless of whether the pose is valid. " ..
"For example, a pose with open cutpoints may have the highest score, but the score is not valid until the cutpoints are closed",
band = "The band functions create and manipulate bands.",
behavior = "The behavior functions control clashing importance and other properties found the client\'s behavior dialog and related places.",
contactmap = "The contactmap functions access contact map information in puzzles which use it.",
creditbest = "The creditbest functions work with the best valid pose, in contrast to the absolutebest functions",
current = "The current functions work with the current pose of the protein.",
dialog = "The dialog functions create the dialog boxes found in many recipes.",
freeze = "The freeze functions freeze and unfreeze the backbone or sidechains of specified segments.",
puzzle = "The puzzle functions get information about the current puzzle. They also allow the puzzle to be reset to a starting point.",
recentbest = "The recentbest functions work with the \"recent best\" pose. Unlike the absolutebest, creditbest, and current poses, the " ..
"recentbest pose can be reset under recipe control.",
recipe = "The recipe functions perform general housekeeping tasks.",
rotamer = "The rotamer functions recipes to manipulate sidechain positions, or rotamers, of a particular segment.",
save = "The save functions allow the current pose to be saved to or restored from numbered \"slots\". ",
"They can also save and restore the secondary structure (helix, sheet, and loop).",
scoreboard = "The scoreboard functions return information about how the current solution relative to other players.",
selection = "The selection functions allows segment to be selected and deselected. Many other functions only work on selected segments.",
structure = "The structure functions perform a variety of tasks related to specific segments of the puzzle." ..
"Most of these tasks can also be performed manually in the client.",
ui = "The ui functions perform miscellaneous \"user interface\" tasks.",
undo = "The undo functions control the undo stack.",
user = "The user functions return information about the logged-in user (player).",
}
--
-- NOOP function table -- lists functions that don't do anything
--
local noopfunc =
{
behavior_GetBandStrengthFactor = "Unimplemented V2 function",
behavior_SetBandStrengthFactor = "Unimplemented V2 function",
behavior_GetWiggleAccuracy = "Unimplemented V2 function",
behavior_SetWiggleAccuracy = "Unimplemented V2 function",
behavior_GetShakeAccuracy = "Unimplemented V2 function",
behavior_SetShakeAccuracy = "Unimplemented V2 function",
behavior_GetBuriedSidechainShakeAccuracy = "Unimplemented V2 function",
behavior_SetBuriedSidechainShakeAccuracy = "Unimplemented V2 function",
behavior_GetExposedSidechainShakeAccuracy = "Unimplemented V2 function",
behavior_SetExposedSidechainShakeAccuracy = "Unimplemented V2 function",
structure_TweakRotate = "Unimplemented V2 function",
structure_TweakShift = "Unimplemented V2 function",
structure_TweakStraighten = "Unimplemented V2 function",
}
--
-- variables used in scanning the input file
--
local ll = 0 -- line count
local oddLine = true
local start
local stop
local tag
local rettype
local funcname
local funcnmsp
local fname2
local rest
local tagcnt = 0
local DEBUG = false
--
-- functabl -- lists functions read from input file
--
-- name - name of function
-- ns - "namespace" (V2 only, structure, band, filter, and so on)
-- ret - return valvue
-- args - arguments
-- desc - description
-- hist - history - V2 name for V1, V1 name for V2
--
local functabl = { { name = "help", ns = "", ret = "void", args = "function Func", desc = "Prints the signature and description of Func, or signature of all Foldit functions if no argument is given.", hist = "" } }
print ( ReVersion )
--
-- I'd like to have an argument, please
--
if arg == nil then
print ( "LuaFunctions is a standalone Lua program " )
print ( "(not a foldit recipe)" )
return
end
if #arg < 2 then
print ( "usage: LuaFunctions helpfile wikifile \[releaseid\] \[V1\]" )
print ( "helpfile is the input, which is the long output of the foldit \"help\" command" )
print ( "wikifile is the output wikia markup" )
print ( "releaseid is the optional foldit release id" )
print ( "V1 is the optional version 1 flag" )
return
end
local frelease = ""
local V1 = false
if #arg >= 3 then
if arg [ 3 ] == "V1" then
V1 = true
print ( "V1 output selected" )
else
frelease = arg [ 3 ]
end
else
frelease = "(releaseid)"
end
if #arg >= 4 then
if arg [ 4 ] == "V1" then
V1 = true
print ( "V1 output selected" )
end
end
--
-- scan input file created by a series of calls to foldit "help" function, each with one function namespace
--
--for line in io.lines ( "K:/Documents/Foldit/LUA functions/functions.20150603a.txt" ) do
for line in io.lines ( arg [ 1 ] ) do
ll = ll + 1
--
-- ignore simple XML tags in foldit scriptlog format
--
start, stop, tag = line:find ( "(<*>)" ) -- not 100% but close enough
if tag ~= nil then
if DEBUG then
print ( "XML tag = " .. line )
end
tagcnt = tagcnt + 1
elseif oddLine then
if DEBUG then
print ( "line " .. ll .. " = \"" .. line .. "\"" )
end
--
-- peel off the return values
--
start, stop, rettype, rest = line:find ( "(%l*)% (.*)" )
if DEBUG then
print ( "return type = " .. rettype .. ", rest = \"" .. rest .. "\"" )
end
--
-- get the function name, including the name space if present
--
start, stop, funcname, rest = rest:find ( "(.*)%((.*)%)" )
if rest == nil then rest = "" end
if funcname == nil then
print ( "ERROR: invalid syntax in line " .. ll .. ", \"" .. line .. "\"" )
start, stop, rettype, funcname = line:find ( "(%l*)% (.*)" )
end
if DEBUG then
print ( "function name = " .. funcname .. ", rest = \"" .. rest .. "\"" )
end
--
-- get the name space
--
start, stop, funcaddr, fname2 = funcname:find ( "(.*)%.(.*)" )
if funcaddr == nil then
funcaddr = ""
else
funcname = fname2
if DEBUG then
print ( "name space = " .. funcaddr .. ", function name = " .. funcname )
end
end
--
-- create the key for the history table lookup
--
local funckey = ""
if funcaddr ~= "" then
funckey = funcaddr
end
funckey = funckey .. "_" .. funcname
local histname = histtabl [ funckey ]
if histname == nil then
histname = "New to V2"
else
--
-- convert names to links
--
local histx = histname
--
-- handle "similar to" to entries
--
local sim = histx:match ( "similar to " )
if sim == nil then
histname = "[[Foldit_Lua_Function_" .. histx .. "|" .. histx .. "]]"
else
local car = histx:sub ( sim:len () )
histname = sim .. "[[Foldit_Lua_Function_" .. car .. "|" .. car .. "]]"
end
end
functabl [ #functabl + 1 ] = { name = funcname, ns = funcaddr, ret = rettype, args = rest, desc = "", hist = histname }
oddLine = not oddLine
else
--
-- for even-numbered lines, just add the text as the description of the last function
--
if #functabl > 0 then
functabl [ #functabl ].desc = line
end
oddLine = not oddLine
end
end
--fout = io.open ( "K:/Documents/Foldit/LUA functions/newmarkup.20150603a.txt", "w" )
fout = io.open ( arg [ 2 ], "w" )
foutf = io.open ( "details.txt", "w" )
fout:write ( "<!-- Foldit Lua Functions automatically generated information -->" .. "\n" )
if V1 then
fout:write ( "[[File:LuaFunctions.v1.png|thumb|400px|Some of the functions which make up version 1 of the Foldit Lua interface.]]\n")
fout:write ( "<p>\'\'\'This page lists the functions found in the obsolete version 1 of the Foldit Lua interface. " ..
"See \[\[Foldit Lua Functions\]\] for the current version 2 functions.</p>" ..
"<p>Note: This page is generated from the output of the help command in the Foldit client. " ..
"Please don't make changes to this page. Changes may be overwritten when the page is regenerated.\'\'\'</p>" ..
"<p>To add details for a particular function, click on the 'Details' link for the function " ..
"and add comments there.</p> " ..
"<p>Use the 'Comments' section below for comments on this page as a whole. " ..
"Comments are preserved when the page is updated.</p>"
)
else
fout:write ( "[[File:LuaFunctions.png|thumb|400px|Some of the functions which make up the Foldit Lua interface.]]\n")
fout:write ( "<p>\'\'\'Note: This page is generated from the output of the help command in the Foldit client. " ..
"Please don't make changes to this page. Changes may be overwritten when the page is regenerated.\'\'\'</p>" ..
"<p>To add details for a particular function, click on the \'Details\' link for the function " ..
"and add comments there.</p>" ..
"<p>Use the \'Comments\' section below for comments on this page as a whole. " ..
"Comments are preserved when the page is updated.</p>" ..
"<p>The functions listed here are for the \"V2\" Foldit Lua interface. " ..
"For each function, the \"V1\" equivalent, if any, is listed. The functions are grouped" ..
" by \[\[Foldit_Lua_V2_Namespaces|namespace\]\].</p>\n"
)
end
fout:write (
"<p>Last updated: release " .. frelease .. "</p>\n"
)
fout:write ( "__TOC__" .. "\n" )
--
-- isolate unimplemented functions with two passes of table
--
local lastnmsp = ""
local funcout = 0
for ii = 1, #functabl do
local funckey = functabl [ ii ].ns .. "_" .. functabl [ ii ].name
if noopfunc [ funckey ] == nil then
funcnmsp = functabl [ ii ].ns
local functext = funcnmsp
if funcnmsp == "" then
funcnmsp = "no_namespace"
functext = "no namespace"
end
if not V1 and funcnmsp ~= lastnmsp then
local nmspdes = nametabl [ funcnmsp ]
fout:write ( "\n<h1>" .. functext .. " functions</h1>\n" )
if nmspdes ~= nil then
fout:write ( "<p>" .. nmspdes .. "</p>\n" )
end
lastnmsp = funcnmsp
end
if V1 then
local lout = "returns="
.. functabl [ ii ].ret .. "|" ..
"namespace="
.. functabl [ ii ].ns .. "|" ..
"functionname="
.. functabl [ ii ].name .. "|" ..
"arguments=("
.. functabl [ ii ].args .. ")|" ..
"description="
.. functabl [ ii ].desc .. "|" ..
"newfunctionname="
.. functabl [ ii ].hist .. "|" ..
"}}" .. "\n"
fout:write ( "{{LuaV1Function|" .. lout )
foutf:write ("{{LuaV1FunctionDetail|" .. lout )
else
local lout = "returns="
.. functabl [ ii ].ret .. "|" ..
"namespace="
.. functabl [ ii ].ns .. "|" ..
"functionname="
.. functabl [ ii ].name .. "|" ..
"arguments=("
.. functabl [ ii ].args .. ")|" ..
"description="
.. functabl [ ii ].desc .. "|" ..
"oldfunctionname="
.. functabl [ ii ].hist .. "|" ..
"}}" .. "\n"
fout:write ( "{{LuaFunction|" .. lout )
foutf:write ( "{{LuaFunctionDetail|" .. lout )
end
funcout = funcout + 1
end
end
local funcoutx = 0
--
-- second pass for unimplemented functions
--
local first = true
for ii = 1, #functabl do
local funckey = functabl [ ii ].ns .. "_" .. functabl [ ii ].name
local noop = noopfunc [ funckey ]
if noop ~= nil then
if first then
first = false
fout:write ( "\n<h1>Unimplemented/disabled functions</h1>\n" )
fout:write ( "<p>Functions in this category do nothing. " ..
"They were either never implemented, or implemented and then removed.</p>"
)
end
fout:write ( "{{LuaFunction|" ..
"returns="
.. functabl [ ii ].ret .. "|" ..
"namespace="
.. functabl [ ii ].ns .. "|" ..
"functionname="
.. functabl [ ii ].name .. "|" ..
"arguments=("
.. functabl [ ii ].args .. ")|" ..
"description="
.. functabl [ ii ].desc .. "|" ..
"oldfunctionname="
.. noop .. "|" ..
"}}" .. "\n"
)
funcoutx = funcoutx + 1
end
end
fout:close ()
foutf:close ()
print ( "--" )
print ( ReVersion .. " complete" )
print ( funcout .. " active functions" )
print ( funcoutx .. " unimplemented functions" )
print ( tagcnt .. " XML tags ignored" )
end
main ()
