Module nwcut
NWC User Tool Execution Environment.
The nwcut library provides function for NWC clip text manipulation.
Getting Started
A typical user tool is constructed as shown below.
-- we want to work with high level nwcItem objects in this script
nwcut.setlevel(2)
for item in nwcut.items() do
local c = item:GetNum('Color')
if (not c) or (c == 0) then
item:Provide("Color")
item.Opts.Color = 4
end
nwcut.writeline(item)
end
Some Important Object Types
- nwcut: Contains the essential utilities that are used by the various support classes.
- nwcItem: The primary object class for storing NWC items.
- nwcPlayContext: An object class for tracking staff play back context, which is helpful in calculating note names, bar counts, etc.
- nwcNotePos: A note position class that tracks the position, accidental, notehead, and other styles for each note
Type nwcut
nwcut.CaptureOptData(Level, ObjType, Tag, Data) |
Used to process NWC text option data as it is captured into a nwcItem object. |
nwcut.ClassifyLine(ln) |
Classifies a line of NWC text to assist in the processing the user tool input. |
nwcut.ClassifyObjType(ObjType) |
Classifies an object type to assist in further processing its contents. |
nwcut.ClassifyOptTag(ObjType, Tag) |
Classifies a NWC text field label to assist in further processing its contents. |
nwcut.GetAccidentalOffset(acc) |
Calculates the pitch offset for the provided accidental character. |
nwcut.GetClefStdCenterTone(clef) |
Calculates the MIDI pitch value at the staff center line for the provided clef type. |
nwcut.GetOffsetAccidental(offset) |
Calculates the accidental that corresponds to a pitch offset. |
nwcut.askbox(msg, msgtitle, flags) |
nwcut question box. |
nwcut.clock() |
Returns the approximate number of CPU seconds used by the script. |
nwcut.getitem() |
Retrieves the next item from the NWC clip text input. |
nwcut.getprop(propName) |
Retrieves a property of the current user tool environment. |
nwcut.items() |
NWC Clip Text item iterator. |
nwcut.loadFile() |
Loads a NWC file into a #nwcFile object instance. |
nwcut.msgbox(msg, msgtitle) |
nwcut message box. |
nwcut.nwcversion() |
Returns the current NWC version. |
nwcut.objtyp(txtLine) |
Extract the object type froma line of NWC text. |
nwcut.prompt(msg, datatype, default) |
nwcut user prompt. |
nwcut.setlevel(lvl) |
Sets the default construction level for nwcut.getitem, nwcut.items, or the nwcItem constructor. |
nwcut.status |
status return code. |
nwcut.warn(...) |
nwcut output warning text. |
nwcut.write(...) |
nwcut standard write function. |
nwcut.writeline(...) |
User tool higher level output function. |
Type nwcFile
nwcFile.Editor |
This contains the nwctxt Editor properties |
nwcFile.Font |
This contains a table map of Font entries. Each entry is mapped by its Style name, and stored as a nwcItem#nwcItem |
nwcFile.PgMargins |
This contains the nwctxt PgMargins properties |
nwcFile.PgSetup |
This contains the nwctxt PgSetup properties |
nwcFile.SongInfo |
This contains the nwctxt SongInfo properties |
nwcFile.Staff |
This is a list of the #nwcStaff objects contained in the file. |
nwcFile:getSelection() |
nwcFile getSelection function returns the staff and index range for the editor selection. |
nwcFile:load(itemIterator) |
nwcFile load function. |
nwcFile.new() |
nwcFile constructor. |
nwcFile:save(writeln) |
nwcFile save function which generates a nwctxt representation. |
Type nwcStaff
nwcStaff.AddStaff |
This contains the nwctxt AddStaff properties |
nwcStaff.Items |
This is a list of the nwcItem#nwcItem notation items found in the staff, which includes notes, bars, and signatures. |
nwcStaff.Lyric |
This contains a list of lyric lines found in the staff, each as a nwcItem#nwcItem |
nwcStaff.Lyrics |
This contains the nwctxt Lyrics config |
nwcStaff.StaffInstrument |
This contains the nwctxt StaffInstrument config |
nwcStaff.StaffProperties |
This contains the nwctxt StaffProperties |
nwcStaff:add(item) |
nwcStaff add a line of nwctxt to the staff. |
nwcStaff.new() |
nwcStaff constructor. |
nwcStaff:save(writeln) |
nwcStaff output function which generates a nwctxt representation. |
Type nwcut.const
nwcut.const.ltyp_Comment |
line contains comment (see nwcut.ClassifyLine) |
nwcut.const.ltyp_Error |
line cannot be classified (see nwcut.ClassifyLine) |
nwcut.const.ltyp_FormatHeader |
line contains header text (see nwcut.ClassifyLine) |
nwcut.const.ltyp_Object |
line contains a notation instruction (see nwcut.ClassifyLine) |
nwcut.const.mode_ClipText |
return value from nwcut.getprop('Mode') when a single staff clip is on the input |
nwcut.const.mode_FileText |
return value from nwcut.getprop('Mode') when an entire NWC file is on the input |
nwcut.const.objtyp_Error |
Unrecognized object type (see nwcut.ClassifyObjType) |
nwcut.const.objtyp_FileProperty |
Object describes a file property (see nwcut.ClassifyObjType) |
nwcut.const.objtyp_StaffLyric |
Object describes a staff lyric (see nwcut.ClassifyObjType) |
nwcut.const.objtyp_StaffNotation |
Object describes a staff notation item (see nwcut.ClassifyObjType) |
nwcut.const.objtyp_StaffProperty |
Object describes one or more staff properties (see nwcut.ClassifyObjType) |
nwcut.const.opt_Associative |
Object field contains associative data (see nwcut.ClassifyOptTag) |
nwcut.const.opt_List |
Object field contains list data (see nwcut.ClassifyOptTag) |
nwcut.const.opt_NotePos |
Object field contains note position data (see nwcut.ClassifyOptTag) |
nwcut.const.opt_Num |
Object field contains a number (see nwcut.ClassifyOptTag) |
nwcut.const.opt_Raw |
Object field contains raw data (see nwcut.ClassifyOptTag) |
nwcut.const.opt_Text |
Object field contains text (see nwcut.ClassifyOptTag) |
nwcut.const.rc_Error |
User tool return value when an error occurs (see nwcut.status) |
nwcut.const.rc_Report |
User tool return value that triggers a report back to the user (see nwcut.status) |
nwcut.const.rc_Success |
User tool return value when a new clip or file has been created (see nwcut.status) |
Type nwcut
Field(s)
- nwcut.CaptureOptData(Level, ObjType, Tag, Data)
-
Used to process NWC text option data as it is captured into a nwcItem object.
Parameters
-
#number Level
: The level of capure that will be performed. -
#string ObjType
: The object type. -
#string Tag
: The field label. -
#string Data
: The actual field data.
Return value
Returns a suitable object that represents the field.
-
- nwcut.ClassifyLine(ln)
-
Classifies a line of NWC text to assist in the processing the user tool input.
Parameter
-
#string ln
: The line of input NWC text that should be classified.
Return value
#number: Returns nwcut.const.ltyp_FormatHeader, nwcut.const.ltyp_Comment, or nwcut.const.ltyp_Object.
-
- nwcut.ClassifyObjType(ObjType)
-
Classifies an object type to assist in further processing its contents.
Parameter
-
#string ObjType
: The object type that should be classified.
Return value
#number: Returns nwcut.const.objtyp_Error, nwcut.const.objtyp_FileProperty, nwcut.const.objtyp_StaffProperty, nwcut.const.objtyp_StaffLyric, or nwcut.const.objtyp_StaffNotation.
-
- nwcut.ClassifyOptTag(ObjType, Tag)
-
Classifies a NWC text field label to assist in further processing its contents.
Parameters
-
#string ObjType
: The object type. -
#string Tag
: The field label.
Return value
#number: Returns nwcut.const.opt_Raw, nwcut.const.opt_Num, nwcut.const.opt_Text, nwcut.const.opt_List, or nwcut.const.opt_Associative.
-
- nwcut.GetAccidentalOffset(acc)
-
Calculates the pitch offset for the provided accidental character.
Parameter
-
#string acc
: The accidental character (as a string)
Return value
#number: Returns the pitch offset for the associated accidental
-
- nwcut.GetClefStdCenterTone(clef)
-
Calculates the MIDI pitch value at the staff center line for the provided clef type.
Parameter
-
#string clef
: The clef type.
Return value
#number: Returns a MIDI pitch
-
- nwcut.GetOffsetAccidental(offset)
-
Calculates the accidental that corresponds to a pitch offset.
Parameter
-
#number offset
: The pitch offset, which can be from -2 up to 2 semitones
Return value
#string: Returns the accidental character that corresponds to the pitch offset
-
- nwcut.askbox(msg, msgtitle, flags)
-
nwcut question box.
Prompts the user with a standard message box. The user is given the opportunity to answer the question, or cancel the user tool.
Parameters
-
msg
: the message text to issue to the user -
msgtitle
: the title for the message box (optional) -
#number flags
: assigns the default action, 1 for Yes (default), and 2 for No
Return value
#number: the answer, 1 for Yes, and 0 for No
-
- nwcut.clock()
-
Returns the approximate number of CPU seconds used by the script.
This can be useful when benchmarking the performance of a script.
Return value
#number: CPU seconds used by script.
- nwcut.getitem()
-
Retrieves the next item from the NWC clip text input.
This function opens the clip text input stream and returns the next notation object as a single line of text.
Return values
-
nwcItem#nwcItem: When the nwcut.setlevel property is set to 1 or more, a nwcItem object is returned for each line of clip text
-
#string: When the nwcut.setlevel property is 0, each raw line of clip text is returned
-
- nwcut.getprop(propName)
-
Retrieves a property of the current user tool environment.
The following propName properties are maintained for each running tool instance:
- FileName - the filename for the current input NWC text (if available)
- SavePending - indicates when a save is pending in the NWC editor
- StartingLine - the starting header for the input clip or file
- EndingLine - the expected ending footer for the input clip or file
- HdrVersion - the version designated within the input header
- Mode - the numeric input mode, which will be nwcut.const.mode_ClipText or nwcut.const.mode_FileText
- ReturnMode - indicates the tool's expected return mode (nwcut.const.mode_ClipText or nwcut.const.mode_FileText)
- ItemLevel - the default level used by nwcut.getitem, nwcut.items, and the nwcItem constructor
Most property values are set by the contents of the input stream. ItemLevel is the exception. It defaults to 0, but can be set using nwcut.setlevel.
Parameter
-
#string propName
: The name of the property to retrieve (from the above list).
Return value
The current value of the property is returned.
- nwcut.items()
-
NWC Clip Text item iterator.
Opens the clip text input stream and returns an iterator function that returns a new notation object represented as a line of text. The construct:
for item in nwcut.items() do *body* end
will iterate over all clip text items. When the iterator function detects the end of the clip text items, it returns nil (to finish the loop).
Return value
an iterator for cycling through NWC text (see nwcut.getitem)
- nwcut.loadFile()
-
Loads a NWC file into a #nwcFile object instance.
This will load the file text input stream into a #nwcFile object instance.
Return value
#nwcFile: An object collection representing everything in the file
- nwcut.msgbox(msg, msgtitle)
-
nwcut message box.
Issues a message to the user with a standard message box. The user is given the opportunity to cancel the user tool.
Parameters
-
msg
: the message text to issue to the user -
msgtitle
: the title for the message box (optional)
Return value
#number: is always 0 when user does not cancel
-
- nwcut.nwcversion()
-
Returns the current NWC version.
Return value
#string: A string describing the host NWC program release version
- nwcut.objtyp(txtLine)
-
Extract the object type froma line of NWC text.
Parameter
-
#string txtLine
: A line of NWC text representing a notation object.
Return value
#string: Returns the object type, for example, Clef, Note, Rest, Bar, etc.
-
- nwcut.prompt(msg, datatype, default)
-
nwcut user prompt.
Prompts the user for additional information. The user is given the opportunity to respond to the prompt, or cancel the user tool.
Parameters
-
msg
: the message text to issue to the user -
datatype
: What kind of control/data is expected (optional, default="*"). Supported types are:- "*" indicates a text response
- "#" indicates a numeric/integer response; the range can be specified in brackets (e.g. "#[-2,5]" supports values from -2 through 5)
- "|" indicates a list of items, each separated by a vertical bar (e.g. "|Note|Bar|Rest" contains a list of three elements)
-
default
: The default data is the user simply accepts the prompt.
Return value
the user response
-
- nwcut.setlevel(lvl)
-
Sets the default construction level for nwcut.getitem, nwcut.items, or the nwcItem constructor.
The level can currently be set from 0 through 2, with 2 creating the most expanded version of a NWC text line. When set to 0, nwcut.getitem returns the raw text stream of NWC text. When set to 1 or more, nwcut.getitem return each NWC text line as a nwcItem object.
Parameter
-
#number lvl
: The default level that should be used by nwcut.getitem, nwcut.items, and the nwcItem constructor.
-
- #number nwcut.status
-
status return code.
Should be set to one of the following:
This field contains the return status code that will be used by NWC in determining how process any output from the user tool. By default, in the absence of any errors, NWC will process the user tool output as a replacement clip or file. This behavior can be changed by assigning one of the nwcut.const constants.
- nwcut.warn(...)
-
nwcut output warning text.
Writes the value of each of its arguments to the standard error stream. The arguments must be strings or numbers. To write other values, use
tostring
orstring.format
.Parameter
-
...
: must be strings or a numbers.
-
- nwcut.write(...)
-
nwcut standard write function.
Writes the value of each of its arguments to the output. The arguments must be strings or numbers. To write other values, use
tostring
orstring.format
beforewrite
.Parameter
-
...
: must be strings or a numbers.
-
- nwcut.writeline(...)
-
User tool higher level output function.
Writes the value of each of its arguments to the output. The arguments can include tables/objects that support the WriteUsing method. A new line is automatically added to the output of this function.
Parameter
-
...
: Any object that supports WriteUsing or the tostring function.
-
Type list_nwcStaff
Type nwcFile
nwcFile object.
The nwcFile object is used to encapsulate a NWC file. The data is kept in fields that match the nwctxt source lines. For example, the nwcFile.SongInfo object contains the file's Title, Author, and Copyright text.
Field(s)
- nwcItem#nwcItem nwcFile.Editor
-
This contains the nwctxt Editor properties
- nwcItem#map_nwcItem nwcFile.Font
-
This contains a table map of Font entries. Each entry is mapped by its Style name, and stored as a nwcItem#nwcItem
- nwcItem#nwcItem nwcFile.PgMargins
-
This contains the nwctxt PgMargins properties
- nwcItem#nwcItem nwcFile.PgSetup
-
This contains the nwctxt PgSetup properties
- nwcItem#nwcItem nwcFile.SongInfo
-
This contains the nwctxt SongInfo properties
- #list_nwcStaff nwcFile.Staff
-
This is a list of the #nwcStaff objects contained in the file.
- nwcFile:getSelection()
-
nwcFile getSelection function returns the staff and index range for the editor selection.
This function assumes an empty selection should be treated as though the entire contents of the staff is selected.
Return value
#nwcStaff, #number, #number: the active staff and selection range from left to right.
- nwcFile:load(itemIterator)
-
nwcFile load function.
Loads an object representation of a NWC clip or file.
Parameter
-
#function itemIterator
: Item iterator function used to receive the nwctxt data
-
- nwcFile.new()
-
nwcFile constructor.
Returns an object representation of a NWCTXT file.
Return value
#nwcFile: an object representation of a NWCTXT file.
- nwcFile:save(writeln)
-
nwcFile save function which generates a nwctxt representation.
Writes an object representation of a NWC clip or file.
Parameter
-
#function writeln
: function used to write the nwctxt data
-
Type nwcStaff
nwcStaff object.
The nwcStaff object is used to encapsulate a NWC staff. The data is kept in fields that match the nwctxt source lines. For example, the nwcStaff.AddStaff object contains the staff's Name and Group properties.
Field(s)
- nwcItem#nwcItem nwcStaff.AddStaff
-
This contains the nwctxt AddStaff properties
- nwcItem#list_nwcItem nwcStaff.Items
-
This is a list of the nwcItem#nwcItem notation items found in the staff, which includes notes, bars, and signatures.
- nwcItem#list_nwcItem nwcStaff.Lyric
-
This contains a list of lyric lines found in the staff, each as a nwcItem#nwcItem
- nwcItem#nwcItem nwcStaff.Lyrics
-
This contains the nwctxt Lyrics config
- nwcItem#nwcItem nwcStaff.StaffInstrument
-
This contains the nwctxt StaffInstrument config
- nwcItem#nwcItem nwcStaff.StaffProperties
-
This contains the nwctxt StaffProperties
- nwcStaff:add(item)
-
nwcStaff add a line of nwctxt to the staff.
Parameter
-
nwcItem#nwcItem item
: to add
-
- nwcStaff.new()
-
nwcStaff constructor.
Returns an object representation of a NWC staff.
Return value
#nwcStaff: an object representation of a NWC staff.
- nwcStaff:save(writeln)
-
nwcStaff output function which generates a nwctxt representation.
Writes an object representation of a NWC staff.
Parameter
-
#function writeln
: function used to write the nwctxt data
-
Type nwcut.const
nwcut constants.
The nwcut.const table contains constants used in processing lines/items from the input.
Field(s)
- nwcut.const.ltyp_Comment
-
line contains comment (see nwcut.ClassifyLine)
- nwcut.const.ltyp_Error
-
line cannot be classified (see nwcut.ClassifyLine)
- nwcut.const.ltyp_FormatHeader
-
line contains header text (see nwcut.ClassifyLine)
- nwcut.const.ltyp_Object
-
line contains a notation instruction (see nwcut.ClassifyLine)
- nwcut.const.mode_ClipText
-
return value from nwcut.getprop('Mode') when a single staff clip is on the input
- nwcut.const.mode_FileText
-
return value from nwcut.getprop('Mode') when an entire NWC file is on the input
- nwcut.const.objtyp_Error
-
Unrecognized object type (see nwcut.ClassifyObjType)
- nwcut.const.objtyp_FileProperty
-
Object describes a file property (see nwcut.ClassifyObjType)
- nwcut.const.objtyp_StaffLyric
-
Object describes a staff lyric (see nwcut.ClassifyObjType)
- nwcut.const.objtyp_StaffNotation
-
Object describes a staff notation item (see nwcut.ClassifyObjType)
- nwcut.const.objtyp_StaffProperty
-
Object describes one or more staff properties (see nwcut.ClassifyObjType)
- nwcut.const.opt_Associative
-
Object field contains associative data (see nwcut.ClassifyOptTag)
- nwcut.const.opt_List
-
Object field contains list data (see nwcut.ClassifyOptTag)
- nwcut.const.opt_NotePos
-
Object field contains note position data (see nwcut.ClassifyOptTag)
- nwcut.const.opt_Num
-
Object field contains a number (see nwcut.ClassifyOptTag)
- nwcut.const.opt_Raw
-
Object field contains raw data (see nwcut.ClassifyOptTag)
- nwcut.const.opt_Text
-
Object field contains text (see nwcut.ClassifyOptTag)
- nwcut.const.rc_Error
-
User tool return value when an error occurs (see nwcut.status)
- nwcut.const.rc_Report
-
User tool return value that triggers a report back to the user (see nwcut.status)
- nwcut.const.rc_Success
-
User tool return value when a new clip or file has been created (see nwcut.status)