Section Batch

Batch processing.

Examples



 --CREATOR: Sylvain
 --NAME: Change score title font
 --BATCH: Score
 -- assume this script is in Scripts > Notation > Score menu
 local n,f,s,c = ChooseFont("Title")
 if n then
    local fl, fs = FontFaceNumberToString(f)
    if BatchIsRecording("Score") == true then
      BatchAdd("Score", "Title font = "..n.." "..s.." "..fl,
        function(score)
          local sty = score.Title.Style
          sty.Font, sty.Face, sty.Size, sty.Color = %n, %fs, %s, %c
          score.Title.String = PurgeStringStyle(score.Title.String)
        end
      )
    elseif FrontScore() ~= nil then
      local sty = FrontScore().Title.Style
      sty.Font, sty.Face, sty.Size, sty.Color = n,fs,s,c
      FrontScore().Title.String = PurgeStringStyle(FrontScore().Title.String)
    end
 end



 -- Demonstrate batch processing
 BatchStartRecording("Score")
 -- Ask for the font
 Run("ChangeTitleFont")
 -- Ask for something else
 -- Include "another script that do crazy things on Score object"
 BatchStopRecording("Score")
 local folder = GetFolderName()
 if folder ~= nil then
     BrowseFolder(folder, "*.myr", function(fileName)
        local score = Load(fileName, false, false, false, false, false, false, false, false, 0)
        BatchExecute("Score", {score})
        return true -- continue browsing
      end
    )
 end
 BatchClear("Score")

Summary

Return type	Function and summary
	BatchAdd(string batchName, string label, function func) Stack a function for batch processing.
	BatchClear(string batchName) Clear the batch stack, in case of cancellation or when all calls are done.
int	BatchExecute(string batchName, Score score, object) Execute the batch function stack on the objects in argument table.
	BatchIsRecording(string batchName) Is the batch currently stacking?
	BatchStartRecording(string batchName) Just set a flag that tells we are currently recording and stacking functions for further batch processing.
	BatchStopRecording(string batchName) Cancel the flag that tells we are recording and stacking operations for batch processing, without clearing the stack.
Symbol	SMFirstSelectedSymbol(Score score, Staff staff, boolean ignoreGhostRest) Returns the first selected symbol (range or individual selection) of the staff or the whole score.
Symbol	SMLastSelectedSymbol(Score score, Staff staff, boolean ignoreGhostRest) Returns the last selected symbol (range or individual selection) of the staff or the whole score.
	TableToElements(table t) Bugfix version of MSLibrary's `PushAllTableElts(t)`, return all elements of a table as multiple return values.

Functions

BatchStartRecording(string batchName)

Just set a flag that tells we are currently recording and stacking functions for further batch processing.

Parameter	Type	Default	Description
batchName	string		Batch name, by convention the type of object function will accept as argument (`"Score"`, `"Staff"`...).

BatchStopRecording(string batchName)

Cancel the flag that tells we are recording and stacking operations for batch processing, without clearing the stack.

Parameter	Type	Default	Description
batchName	string		Batch name, by convention the type of object function will accept as argument (`"Score"`, `"Staff"`...).

Return: int Stack size

BatchIsRecording(string batchName)

Is the batch currently stacking?

If yes, then function must be stacked by BatchAdd, else performed directly.

Parameter	Type	Default	Description
batchName	string		Batch name, by convention the type of object function will accept as argument (`"Score"`, `"Staff"`...).

Return

bvool true if recording, nil (for false) if not

Example



     if BatchIsRecording("Score") == true then
      BatchAdd("Score", "My action", MyFunction)
    else
      MyFunction(FrontScore())
    end

BatchAdd(string batchName, string label, function func)

Stack a function for batch processing.

Parameter	Type	Description
batchName	string	Batch name, by convention the type of object function will accept as argument (`"Score"`, `"Staff"`...).
label	string	Just a label to show progression or report an error with context.
func	function	The function that will be performed later, by BatchExecute. If `batchName` is a conventional objet type (`"Score"`, `"Instrument"`...) then the first argument must be of that type. In most cases, a Score object is given as a second argument, the function can ignore it. No return value is expected. In case of error, call `throw("Error message", true)`, `true` means visual alert, `false` console only.

BatchClear(string batchName)

Clear the batch stack, in case of cancellation or when all calls are done.

Parameter	Type	Default	Description
batchName	string		Batch name, by convention the type of object function will accept as argument (`"Score"`, `"Staff"`...).

BatchExecute(string batchName, Score score, object)

Execute the batch function stack on the objects in argument table.

Parameter	Type	Default	Description
batchName	string		Batch name, by convention the type of object function will accept as argument (`"Score"`, `"Staff"`...).
score	Score		If needed, the score on which the batch will be processed
object		nil	The object (Staff, Instrument...) that will be given as first argument to each function in the stack.

Return: int: Number of functions called.

TableToElements(table t)

Bugfix version of MSLibrary's PushAllTableElts(t), return all elements of a table as multiple return values.

PushAllTableElts(...) doesn't hnandle string nor complex objects, this version does.

Parameter	Type	Default	Description
t	table		If table is indexed as `t = {1, "b", 3}` then values are returned in their order. Else if table is made of pairs variable to value like in `t = {A=1, B="b", C=3}` order is not guaranteed.

Return

All values of the table

Error

if not enough free stack / too big table

Example



 local t = {1, "b", 3, FrontScore()}
 print(TableToElements(t)) --> 1 b 3 userdata(...)
 -- PushAllTableElts(t) returns 1 nil 3 and crashes

SMFirstSelectedSymbol(Score score, Staff staff, boolean ignoreGhostRest)

Returns the first selected symbol (range or individual selection) of the staff or the whole score.

This function is more accurate than Staff.FirstSelectedSymbol, handles individual selection, and the 3rd argument allows you to ignore ghost rests.

Note: like Staff.FirstSelectedSymbol, the returned symbol may not be included in actions applied to selection (in Edit menu). If the range selection is after the note head but before next note, it is considered as selected by MyrScript, whereas actions in Edit menu won't apply to it.

Parameter	Type	Description
score	Score	score
staff	Staff	If `nil`, look for selected symbol on all staves and return the one that begins the first (least `symbol.Time`)
ignoreGhostRest	boolean	If first selected symbol is a ghost rest, go forward until another kind of symbol is found

Return: Symbol: or nil if selection contains no symbol

SMLastSelectedSymbol(Score score, Staff staff, boolean ignoreGhostRest)

Returns the last selected symbol (range or individual selection) of the staff or the whole score.

This function is more accurate than Staff.LastSelectedSymbol, handles individual selection, and the 3rd argument allows you to ignore ghost rests.

Note: like Staff.LastSelectedSymbol, the returned symbol may not be included in actions applied to selection (in Edit menu). If the range selection is after the note head but before next note, it is considered as selected by MyrScript, whereas actions in Edit menu won't apply to it.

Parameter	Type	Description
score	Score	score
staff	Staff	If `nil`, look for selected symbol on all staves and return the one that ends the last (greatest `symbol.Time + symbol.Duration`)
ignoreGhostRest	boolean	If last selected symbol is a ghost rest, go backward until another kind of symbol is found

Return: Symbol: or nil if selection contains no symbol