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

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

  1. nwcItem#nwcItem: When the nwcut.setlevel property is set to 1 or more, a nwcItem object is returned for each line of clip text

  2. #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:

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

Copyright © 2020 NoteWorthy Software™, Inc.
All Rights Reserved.