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

  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: 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 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 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 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

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)