Module `nwcut`

NWC User Tool Execution Environment.

The nwcut library provides function for NWC clip text manipulation.

Getting Started

A simple user tool is shown below:

    -- Set color to highlight 4 for all items that use default color
    local function filterProc(item)
        if item:IsFake() then return end
        if (item:GetNum('Color') or 0) == 0 then
            item:Set('Color',4)
        end
    end

    nwcut.loadFile()
        :forSelection(filterProc)
        :save()

Some Important Object Types

nwcut: Contains the essential utilities that are used by the various support classes.
nwcFile: Class for storing user tool input (can store a clip or a whole work).
nwcStaff: Class for storing each staff.
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.decodeText(data)	Decodes a nwctxt text field.
nwcut.encodeText(data)	Encodes a text field so that it can be safely included in a nwctxt file.
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, listvals, 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.typeOf(obj)	Returns the current object's class name ID, or its simple type.
nwcut.warn(...)	nwcut output warning text.
nwcut.write(...)	nwcut standard write function.
nwcut.writeline(...)	User tool higher level output function.

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

#string: Returns raw,number,text,list,assoc,notepos,or utext.

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.decodeText(data)

Decodes a nwctxt text field.

Parameter

#string data : The nwctxt data field that should be decoded.

Return value

#string: Returns the decoded string.

nwcut.encodeText(data)

Encodes a text field so that it can be safely included in a nwctxt file.

Parameter

#string data : The data field that should be encoded.

Return value

#string: Returns the encoded string.

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#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, listvals, 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 multi-line text response
- "#" indicates a numeric/integer response; the range and spin value can be specified in brackets (e.g. "#[-2,5,1]" supports values from -2 through 5, by 1)
- "|" indicates a list of items, each separated by a vertical bar (e.g. "|Note|Bar|Rest" contains a list of three elements)
- "&" indicates a list of multi-selectable items, which are provided in the listvals parameter; the default must be a table of strings pre-selected strings from listvals; returns a table of selected strings
listvals : For "&" multi-select lists, this is a table of strings, otherwise this parameter should not be included (optional)
default : The default data is the user simply accepts the prompt (optional)

Return value

the user response, which can be a table, string, or number

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:

nwcut.const.rc_Success
nwcut.const.rc_Report
nwcut.const.rc_Error

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.typeOf(obj)

Returns the current object's class name ID, or its simple type.

Parameter

obj : A nwcut object instance.

Return value

#string: A string describing the object's class type, which will be its class name or its simple type

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 or string.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 or string.format before write.

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 `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)

Module nwcut

Getting Started

Some Important Object Types

Type nwcut

Type nwcut.const

Type nwcut

Field(s)

Parameters

Return value

Parameter

Return value

Parameter

Return value

Parameters

Return value

Parameter

Return value

Parameter

Return value

Parameter

Return value

Parameters

Return value

Return value

Parameter

Return value

Parameter

Return value

Return values

Parameter

Return value

Return value

Return value

Parameters

Return value

Return value

Parameter

Return value

Parameters

Return value

Parameter

Parameter

Return value

Parameter

Parameter

Parameter

Type nwcut.const

Field(s)

Module `nwcut`

Type `nwcut`

Type `nwcut.const`

Type `nwcut`

Type `nwcut.const`