Module `nwcItem`

An object representing a single item of clip text.

Each line returned by nwcut#nwcut.getitem or nwcut#nwcut.items can be used to construct a nwcItem object, which includes properties and methods for analyzing, altering, and reconstructing a line of NWC text.

Type `nwcItem`

nwcItem:AllNotePositions()	Iterate through all note positions.
nwcItem:ContainsNotes()	Indicates whether this object contains a one or more note positions.
nwcItem.Fake	Defained as true when the item is a fake NWC item (use of the IsFake method is recommended)
nwcItem:Get(...)	Safely retrieve any nested Opts value, or nil if it cannot be found.
nwcItem:GetNum(...)	Safely retrieve any nested numeric Opts value, or nil if it cannot be found.
nwcItem:GetUserType()	Get the subtype of a User object.
nwcItem:HasDuration()	Returns true if this object has a play back duration.
nwcItem.ID	Contains the name of the object type (nwcItem)
nwcItem:Is(t)	Determine the NWC object type.
nwcItem:IsFake()	Is this object fake.
nwcItem:IsNoteRestChord()	Is this object a Note, Rest, or Chord.
nwcItem:NoteDots(durVoice)	If the item is a note type, then returns the number of augmentation dots in the duration.
nwcItem:NoteDurBase(durVoice)	Returns the base duration string for a note or rest item (defined in `nwc.txt.NoteDurBase`).
nwcItem.ObjType	Indicates the type of NWC object, such as Clef, Key, Note, Chord, Rest, etc.
nwcItem.Opts	Contains all of the options for the object referenced as a table of name,value pairs
nwcItem:Provide(lbl, data)	Used to establish (if necessary) and return a named option field.
nwcItem.UserType	Indicates the User Object Type when the ObjType is User
nwcItem:WriteUsing(writeFunc)	NWC text output function with a user specified write function.
nwcItem:__tostring()	Converts an object to NWC text.
nwcItem.new(cliptext, level)	nwcItem constructor.

Type `nwcItem`

Field(s)

nwcItem:AllNotePositions()

Iterate through all note positions.

Return value

An iterator of all note positions (from both Pos and Pos2), starting from the lowest note.

nwcItem:ContainsNotes()

Indicates whether this object contains a one or more note positions.

Return value

#boolean: Indicating whether this object contains a one or more note positions.

#boolean nwcItem.Fake: Defained as true when the item is a fake NWC item (use of the IsFake method is recommended)

nwcItem:Get(...)

Safely retrieve any nested Opts value, or nil if it cannot be found.

This is the easiest way to retrieve any Opts value from the object. You can drill into the Opts table by adding additional key names into the argument list. For example, the line:

local stemDir = item:Get('Opts','Stem') or "Up"

could be used to get the stem direction for a note, or assume it is Up if the stem direction is not set.

Parameter

... : One or more key names indexing into the Opts table.

Return value

the option value if it exists, or nil.

nwcItem:GetNum(...)

Safely retrieve any nested numeric Opts value, or nil if it cannot be found.

This is the easiest way to retrieve any numeric Opts value from the object. This behaves just like Get, but returns a number or nil. For example, a dynamic velocity override could be retrieved like so: local noteVel = item:GetNum("Opts","Velocity") or -1

Parameter

... : One or more key names indexing into the Opts table.

Return value

#number: the numeric option value, or nil if it does not exist or is not a number.

nwcItem:GetUserType()

Get the subtype of a User object.

Only returns a valid user type when the ObjType is User.

Return value

#string: the user type name or false

nwcItem:HasDuration()

Returns true if this object has a play back duration.

Hint: grace notes do not have duration.

Return value

#boolean: True when the object is a note or rest with duration

#string nwcItem.ID: Contains the name of the object type (nwcItem)

nwcItem:Is(t)

Determine the NWC object type.

Parameter

#string t : A string, such as "Clef", "Note", or "Bar"

Return value

#boolean: Returns true if this object's ObjType matches the specified string.

nwcItem:IsFake()

Is this object fake.

Fake objects do not need to be passed to the output of a user tool.

Return value

#boolean: True when the object is either fake or just context

nwcItem:IsNoteRestChord()

Is this object a Note, Rest, or Chord.

Return value

#boolean:

nwcItem:NoteDots(durVoice)

If the item is a note type, then returns the number of augmentation dots in the duration.

Returns 0 in all other cases.

Parameter

#number durVoice : Which voice to use; can be 'Dur','Dur2',1,2; defaults to 'Dur'.

Return value

#number: Returns 0, 1, or 2

nwcItem:NoteDurBase(durVoice)

Returns the base duration string for a note or rest item (defined in nwc.txt.NoteDurBase).

Parameter

#number durVoice : Which voice to get; can be 'Dur','Dur2',1,2; defaults to 'Dur'.

Return value

#string: Returns one of nwc.txt.NoteDurBase or nil

#string nwcItem.ObjType: Indicates the type of NWC object, such as Clef, Key, Note, Chord, Rest, etc.

#table nwcItem.Opts: Contains all of the options for the object referenced as a table of name,value pairs

nwcItem:Provide(lbl, data)

Used to establish (if necessary) and return a named option field.

Use the Provide function to guarantee that an option field exists in the object and is constructed of the correct option type. If the option type is an object (not opt_Raw), then it can be used directly from the return of this function.

    item = nwcItem.new("|Ending")

    -- Include a first ending
    item:Provide("Endings")["1"] = ""

    -- Add a default visibility if one is not set
    item:Provide("Visibility","Default")

Parameters

lbl : The name of the option (a key into the Opts table).
data : Default data for the option if it does not yet exist (optional, default is an empty string).

Return value

the option object or value.

#string nwcItem.UserType: Indicates the User Object Type when the ObjType is User

nwcItem:WriteUsing(writeFunc)

NWC text output function with a user specified write function.

This method is used to reconstruct a line of NWC text and output it using a user-specified write function

Parameter

writeFunc : The function that will be used to write the pieces that constitute the NWC text

nwcItem:__tostring()

Converts an object to NWC text.

This method is used when the tostring operator is applied to a nwcItem object (refer to the global section)

Return value

#string: a line of NWC text.

nwcItem.new(cliptext, level)

nwcItem constructor.

Returns an object representation of a single clip item.

Parameters

#string cliptext : A line of clip text returned by nwcut#nwcut.getitem or nwcut#nwcut.items
#number level : Controls how many recursive levels of construction should be done (optional)

Return value

#nwcItem: an object representation of a single line of NWC text.

Module `nwcItem`

Type `nwcItem`

Type `nwcItem`

Field(s)

Return value

Return value

Parameter

Return value

Parameter

Return value

Return value

Return value

Parameter

Return value

Return value

Return value

Parameter

Return value

Parameter

Return value

Parameters

Return value

Parameter

Return value

Parameters

Return value

Type `list_nwcItem`

Type `map_nwcItem`

Module nwcItem

Type nwcItem

Type nwcItem

Field(s)

Return value

Return value

Parameter

Return value

Parameter

Return value

Return value

Return value

Parameter

Return value

Return value

Return value

Parameter

Return value

Parameter

Return value

Parameters

Return value

Parameter

Return value

Parameters

Return value

Type list_nwcItem

Type map_nwcItem

Module `nwcItem`

Type `nwcItem`

Type `nwcItem`

Type `list_nwcItem`

Type `map_nwcItem`