Class: String

Inherits:
Object show all
Defined in:
lib/musa-dsl/neumas/string-to-neumas.rb,
lib/musa-dsl/neumas/string-to-neumas.rb,
lib/musa-dsl/neumas/string-to-neumas.rb,
lib/musa-dsl/neumas/string-to-neumas.rb,
lib/musa-dsl/neumas/string-to-neumas.rb,
lib/musa-dsl/neumas/string-to-neumas.rb

Instance Method Summary collapse

Instance Method Details

#n(decode_with: nil, debug: nil) ⇒ Object

Note:

This method is added to String via refinement. Requires using Musa::Extension::Neumas.

Short alias for to_neumas.

See Also:



297
 
# File 'lib/musa-dsl/neumas/string-to-neumas.rb', line 297

class ::String; end

#neumas(decode_with: nil, debug: nil) ⇒ Object

Note:

This method is added to String via refinement. Requires using Musa::Extension::Neumas.

Alias for to_neumas.

See Also:



287
 
# File 'lib/musa-dsl/neumas/string-to-neumas.rb', line 287

class ::String; end

#nn(decode_with: nil, debug: nil) ⇒ Object

Note:

This method is added to String via refinement. Requires using Musa::Extension::Neumas.

Short alias for to_neumas_to_node.

See Also:



307
 
# File 'lib/musa-dsl/neumas/string-to-neumas.rb', line 307

class ::String; end

#to_neumas(decode_with: nil, debug: nil) ⇒ Serie, Array

Note:

This method is added to String via refinement. Requires using Musa::Extension::Neumas.

Parses neuma notation string to structured neumas.

Uses Neumalang parser to convert text notation into GDVD (differential) neuma objects that can be decoded to GDV events.

Examples:

Parse simple melody

using Musa::Extension::Neumas
neumas = "(0) (+2) (+2) (-1) (0)".to_neumas

# Each element is a { kind:, gdvd: } envelope; the gdvd is what was written.
neumas.i.to_a.map { |n| n[:gdvd] }
# => [{ abs_grade: 0 }, { delta_grade: 2 }, { delta_grade: 2 },
#     { delta_grade: -1 }, { abs_grade: 0 }]

Flats, and the digit-separator trap

"(+2_) (+2_2) (+1_/2)".to_neumas.i.to_a.map { |n| n[:gdvd] }
# => [{ delta_grade: 2, delta_sharps: -1 },
#     { delta_grade: 22 },
#     { delta_grade: 1, delta_sharps: -1, factor_duration: (1/2) }]

# `_` after a grade is a flat. `_` BETWEEN DIGITS is Ruby's own digit
# separator, so `+2_2` is grade 22 and not a doubly-flattened 2.
# There is no error and no warning: the notation is valid, it just
# means something else. Write a double flat as `+2__`.

Absolute and relative grades

"(0) (+2) (4) (+1)".to_neumas.i.to_a.map { |n| n[:gdvd] }
# => [{ abs_grade: 0 }, { delta_grade: 2 },
#     { abs_grade: 4 }, { delta_grade: 1 }]

# A grade with no sign is ABSOLUTE wherever it appears, so a phrase
# can re-anchor itself in the middle without leaving relative mode.

Dynamics are a signed step, not a level

"(0 pp) (0 p) (0 mp) (0 mf) (0 f) (0 ff) (0 fff)".to_neumas
  .i.to_a.map { |n| n[:gdvd][:abs_velocity] }
# => [-2, -1, 0, 1, 2, 3, 4]

# `mp` is 0: the mark names a position on a scale centred there, and
# what travels is the number.

Parse with immediate decoding

using Musa::Extension::Neumas
# Create a simple decoder
decoder = Musa::Neumas::Decoders::NeumaDifferentialDecoder.new
result = "(0) (+2) (+2) (-1) (0)".to_neumas(decode_with: decoder)

# Decoding unwraps the envelope: the elements ARE the gdvd now.
result.i.to_a
# => [{ abs_grade: 0 }, { delta_grade: 2 }, { delta_grade: 2 },
#     { delta_grade: -1 }, { abs_grade: 0 }]

Parse with debug

using Musa::Extension::Neumas
neumas = "(0) (+2) (+2)".to_neumas(debug: true)

# `debug:` only makes the parser narrate to stdout; what comes back is
# the same series it would return without it.
neumas.i.to_a.map { |n| n[:gdvd] }
# => [{ abs_grade: 0 }, { delta_grade: 2 }, { delta_grade: 2 }]

Parameters:

  • decode_with (Decoder, nil) (defaults to: nil) —

    optional decoder to apply immediately

  • debug (Boolean, nil) (defaults to: nil) —

    enable debug output from parser

Returns:

  • (Serie, Array) —

    parsed neuma series or array



224
 
# File 'lib/musa-dsl/neumas/string-to-neumas.rb', line 224

class ::String; end

#to_neumas_to_node(decode_with: nil, debug: nil) ⇒ Node

Note:

This method is added to String via refinement. Requires using Musa::Extension::Neumas.

Parses neuma notation and converts to generative node.

Combines parsing with node conversion for use in generative grammars.

Examples:

Convert to node for generative grammar

using Musa::Extension::Neumas
node = "(0) (+2) (+2) (-1) (0)".to_neumas_to_node

# One option holding one sequence: the whole phrase is a single
# alternative, ready to be combined with | and + in a grammar.
node.options.size        # => 1
node.options.first.size  # => 1
node.options.first.first.i.to_a.map { |n| n[:gdvd] }
# => [{ abs_grade: 0 }, { delta_grade: 2 }, { delta_grade: 2 },
#     { delta_grade: -1 }, { abs_grade: 0 }]

Parameters:

  • decode_with (Decoder, nil) (defaults to: nil) —

    optional decoder to apply

  • debug (Boolean, nil) (defaults to: nil) —

    enable debug output

Returns:

  • (Node) —

    generative node structure

See Also:

  • Musa::Generative


253
 
# File 'lib/musa-dsl/neumas/string-to-neumas.rb', line 253

class ::String; end

#|(other) ⇒ Hash

Note:

This method is added to String via refinement. Requires using Musa::Extension::Neumas.

Creates parallel neuma structure.

Combines two neuma strings into parallel (polyphonic) structure. Both voices are parsed and wrapped in parallel container.

Examples:

Two-voice harmony

using Musa::Extension::Neumas

melody = "(0) (+2) (+4) (+5)"
bass = "(-7) (-5) (-3) (-1)"
harmony = melody | bass

Parameters:

  • other (String) —

    second neuma string to parallelize

Returns:

  • (Hash) —

    parallel neuma structure with two series

Raises:

  • (ArgumentError) —

    if other is not a String



277
 
# File 'lib/musa-dsl/neumas/string-to-neumas.rb', line 277

class ::String; end