alda-rb 0.2.1 → 0.3.1

data/examples/marriage_d_amour.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require 'alda-rb'
+
+# Marriage D' Amour
+#
+# Richard Clayderman
+# Paul de Senneville
+#
+# sheet music:
+# https://musescore.com/user/153958/scores/154629
+
+using Alda::Sequence::RefineFlatten
+
+module Alda::EventList
+	def up8 &block
+		result = block.()
+		result.events = result.events.map do |event|
+			if event.is_event_of? Alda::Octave
+				event
+			else
+				if event.respond_to? :labels
+					labels = event.labels
+					event.labels = []
+				end
+				sequence = Alda::Sequence.new
+				sequence.events = [Alda::Chord.new(
+					event,
+					+Alda::Octave.new(''),
+					event,
+					-Alda::Octave.new('')
+				)]
+				container = Alda::EventContainer.new(sequence, result)
+				container.labels = labels || []
+				container
+			end
+		end
+		result
+	end
+end
+
+Alda::Score.new do
+	key_sig! 'b- e-'
+	tempo! 80
+	piano_ 'right'
+	piano_ 'left'
+	
+	right_
+	r2_4_8_16 o5 g16
+	left_
+	o2 g8 o! d b d b d b d
+	
+	motif1 = -> do
+		right_
+		g16 a a b b a a g g d d o? b b g g o! f f e e d e f e4_8
+		left_
+		o2 g o! d b d b d b d e g o! e o? g o! e o? g
+		
+		right_
+		v1 r16 e e f f g g a a f f c c e e d d c d e _marker1 d8_4
+		v2 __marker1 r8 o6 d32 o! d8_16_32 v0
+		left_
+		v1 o? f o! c a c a c a o? b o! f o! d o? d8_4
+		v2 __marker1 r8 o4 g4? v0
+	end
+	motif1.()
+	
+	motif2 = -> do
+		right_
+		o5 s{ (d8 o? g16 b o! d c)*2; d8 (o? g16 b o! e d e8)*2; e16 d e e_ f8 f16 g f g d4_8 o!}*2
+		left_
+		s{o2 g8 o! d b d b d o? g o! d b c g o! e o? g o! e o? g o? f o! c a o? b
+		(o! b o? up8{s{a}})%1; up8{b a}%2}*2
+	end
+	motif2.()
+	
+	motif3 = -> do
+		right_
+		o5 b8_16 d16 d e e8_16 c16 a g a8_16 c16 c d d8 o? b16 b o! g f g8_16 o? b16 b o! c c8_16 o? a16 o! d c d4_8
+		left_
+		up8{s{g}}; o! d b c g o! e o? o? f o! c a o? b o! f o? a g o! d b o? a o! e o! c o? d o? up8{e_ g?}
+	end
+	motif3.()
+	
+	tt2 { s{o2 g o! d b c g o! e o? o? f o! c a o? b o! b o? up8{s{a}}; g o! d b c g o! e o? o? f o! c a o? g o! d b}*2 }
+	motif4 = -> do
+		tt1 = -> { (o5 b8_16 b16 b o! c c8_16 o? b16 a g f8_16 f16 g f d4_8%1)*2 }
+		right_
+		tt1.(); g4_8; up8{tt1.()}
+		left_
+		tt2 o4 d g b
+	end
+	motif4.()
+	right_; up8{s{g2_4}}
+	
+	motif2.()
+	
+	motif4.()
+	right_
+	o5 up8{s{g2_8}}; r16 g16
+	
+	motif1.()
+	motif2.()
+	motif3.()
+	
+	tt1 = -> { (o5 b8_16 b16 b o! c c8_16 o? b16 a g f8_16 f16 g f d4_8%1)*2 }
+	
+	right_
+	tt1.(); g4_8
+	-> { up8{tt1.()}; up8{s{g4_8}} }*2
+	up8{tt1.()}; up8{s{g1}}
+	left_
+	tt2*2; o4 d g o! d g r8_16 o! g4_8
+end.play

data/examples/multi_poly.rb

@@ -3,8 +3,8 @@
 require 'alda-rb'
 
 Alda::Score.new do
-	piano_ set_duration 4
-	harp_  set_duration 2; octave 3
+	piano_; set_duration 4
+	harp_;  set_duration 2; octave 3
 	
 	piano_/harp_
 	t{ e f g }; t{ a b o! c }

data/examples/track-volume.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require 'alda-rb'
+
+Alda::Score.new do
+	tempo! 105
+	
+	piano_
+	pmotif do
+		s do
+			o3
+			vol 100; a16
+			vol 90;  -b
+			vol 80;  a
+			vol 70;  -b
+			vol 60;  o! c d
+			vol 50;  e f
+		end * 2
+	end
+	
+	70.step(10, -20) { track_vol _1; pmotif }
+	
+	clarinet_
+	cmotif do
+		quant 100; o5
+		vol 60; d8
+		vol 70; c
+		vol 80; o? +f2_4
+	end
+	
+	10.step(70, 20) { track_vol _1; cmotif }
+end.play

data/examples/variables-2.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require 'alda-rb'
+
+Alda::Score.new do
+	quiet { vol 25 }
+	loud { vol 50 }
+	louder { vol 75 }
+	
+	notes { c d e }
+	
+	piano_
+	quiet notes
+	loud notes
+	louder notes
+end.play

data/exe/alda-irb

@@ -0,0 +1,32 @@
+#!/usr/bin/env ruby
+
+require 'alda-rb'
+require 'optparse'
+
+HELP = 'Print this help message and exit'.freeze
+HOST = 'The hostname of the Alda REPL server; only useful in Alda 2; see `alda repl --help`'.freeze
+PORT = 'The port of the Alda REPL server; only useful in Alda 2; see `alda repl --help`'.freeze
+NO_COLOR = 'Whether the output should not be colored'.freeze
+NO_PREVIEW = 'Whether a preview of what Alda code will not be played everytime you input ruby codes'.freeze
+NO_RELINE = 'Whether to use Reline to read input'.freeze
+
+host = 'localhost'
+port = -1
+color = true
+preview = true
+reline = true
+
+OptionParser.new do |opts|
+	opts.banner = 'Usage: alda-irb [options]'
+	opts.on('-h', '--help', HELP) { exit unless puts opts }
+	opts.on('-H', '--host string', HOST) { host = _1 }
+	opts.on('-p', '--port int', PORT) { port = _1 }
+	opts.on('-c', '--no-color', NO_COLOR) { color = false }
+	opts.on('-P', '--no-preview', NO_PREVIEW) { preview = false }
+	opts.on('-r', '--no-reline', NO_RELINE) { reline = false }
+end.parse!
+
+Alda.deduce_generation
+opts = { color: color, preview: preview, reline: reline }
+opts.merge! host: host, port: port unless Alda.v1?
+Alda::REPL.new(**opts).run

data/lib/alda-rb/commandline.rb

@@ -1,3 +1,5 @@
+##
+# Adding functions that is accessible everywhere.
 module Kernel
 	##
 	# :call-seq:
@@ -19,7 +21,24 @@ end
 module Alda
 	
 	##
-	# The array of available subcommands of alda executable.
+	# The Array of possible values of ::generation.
+	# It is just the array <tt>[:v1, :v2]</tt>
+	#
+	# You can use +:v1?+ and +:v2?+ to get whether the current generation is +:v1+ or +:v2+.
+	# For example, <tt>Alda.v1?</tt> is the same as <tt>Alda.generation == :v1</tt>.
+	# You can also use +:v1!+ and +:v2!+ to set the generation to +:v1+ or +:v2+.
+	# For example, <tt>Alda.v1!</tt> is the same as <tt>Alda.generation = :v1</tt>.
+	GENERATIONS = %i[v1 v2].freeze
+	
+	GENERATIONS.each do |gen|
+		module_function define_method("#{gen}?") { @generation == gen }
+		module_function define_method("#{gen}!") { @generation = gen }
+	end
+	
+	##
+	# The available subcommands of alda executable.
+	# This is a Hash, with keys being possible values of ::generation,
+	# and values being an Array of symbols of the available commands of that generation.
 	#
 	# Alda is able to invoke +alda+ at the command line.
 	# The subcommand is the name of the method invoked upon Alda.
@@ -36,37 +55,45 @@ module Alda
 	#   Alda.parse code: 'bassoon: o3 c'
 	#   # => "{\"chord-mode\":false,\"current-instruments\":...}\n"
 	#
-	# The available commands are: +help+, +update+, +repl+, +up+,
-	# +start_server+, +init+, +down+, +stop_server+, +downup+, +restart_server+,
-	# +list+, +status+, +version+, +play+, +stop+, +parse+, +instruments+, and
-	# +export+.
-	COMMANDS = %i[
-		help update repl up start_server init down stop_server
-		downup restart_server list status version play stop parse
-		instruments export
-	].freeze
+	# The available commands are:
+	#
+	# * If ::generation is +:v1+:
+	#   +help+, +update+, +repl+, +up+, +start_server+, +init+, +down+, +stop_server+,
+	#   +downup+, +restart_server+, +list+, +status+, +version+, +play+, +stop+, +parse+,
+	#   +instruments+, and +export+.
+	# * If ::generation is +:v2+:
+	#   +doctor+, +export+, +help+, +import+, +instruments+, +parse+, +play+,
+	#   +ps+, +repl+, +shutdown+, +stop+, +telemetry+, +update+, and +version+.
+	#
+	# Trying to run a command that is not support by the current generation set by ::generation
+	# will raise an Alda::GenerationError.
+	COMMANDS_FOR_VERSIONS = {
+		v1: %i[
+			help update repl up start_server init down stop_server
+			downup restart_server list status version play stop parse
+			instruments export
+		].freeze,
+		v2: %i[
+			doctor export help import instruments parse play ps repl shutdown stop
+			telemetry update version
+		].freeze
+	}.freeze
 	
-	COMMANDS.each do |command|
+	##
+	# The Hash of available commands.
+	# The symbols of commands are keys
+	# and each value is an Array of generations where the command is available.
+	COMMANDS = COMMANDS_FOR_VERSIONS.each_with_object({}) do |(gen, commands), r|
+		commands.each { (r[_1] ||= []).push gen }
+	end.freeze
+	
+	COMMANDS.each do |command, generations|
 		define_method command do |*args, **opts|
-			block = ->key, val do
-				next unless val
-				args.push "--#{key.to_s.tr ?_, ?-}"
-				args.push val.to_s unless val == true
-			end
-			# executable
-			args.unshift Alda.executable
-			args.map! &:to_s
-			# options
-			Alda.options.each &block
-			# subcommand
-			args.push command.to_s
-			# subcommand options
-			opts.each &block
-			# subprocess
-			IO.popen(args, &:read).tap do
-				raise CommandLineError.new $?, _1 if $?.exitstatus.nonzero?
-			end
-		end
+			Alda::GenerationError.assert_generation generations
+			result = Alda.pipe command, *args, **opts, &:read
+			raise CommandLineError.new $?, result if $?.exitstatus.nonzero?
+			result
+		end.tap { module_function _1 }
 	end
 	
 	class << self
@@ -84,6 +111,19 @@ module Alda
 		# Clear it using ::clear_options.
 		attr_reader :options
 		
+		##
+		# The major version of the +alda+ command used.
+		# Possible values: +:v1+ or +:v2+ (i.e. one of the values in Alda::GENERATIONS).
+		# If you try to specify it to values other than those, an ArgumentError will be raised.
+		# This affects several things due to some incompatible changes from \Alda 1 to \Alda 2.
+		# You may use ::deduce_generation to automatically set it,
+		# or use #v1! or #v2! to set it in a shorter way.
+		attr_accessor :generation
+		def generation= gen # :nodoc:
+			raise ArgumentError, "bad generation: #{gen}" unless GENERATIONS.include? gen
+			@generation = gen
+		end
+		
 		##
 		# :call-seq:
 		#   Alda[**opts] -> self
@@ -91,6 +131,7 @@ module Alda
 		# Sets the options of alda command.
 		# Not the subcommand options.
 		#
+		#   # This example only works for Alda 1.
 		#   Alda[port: 1108].up # => "[1108] ..."
 		#   Alda.status # => "[1108] ..."
 		#
@@ -115,14 +156,104 @@ module Alda
 	
 	@executable = 'alda'
 	@options = {}
+	@env = {
+		'ALDA_DISABLE_SPAWNING' => 'yes',
+		'ALDA_DISABLE_TELEMETRY' => 'yes'
+	}
+	v2!
+	
+	##
+	# :call-seq:
+	#   env() -> Hash
+	#   env(hash) -> Hash
+	#   env(hash) { ... } -> Object
+	#
+	# When called with no arguments,
+	# returns the commandline environment variables (a Hash)
+	# used when running +alda+ on command line.
+	# It is <tt>{"ALDA_DISABLE_SPAWNING"=>"yes","ALDA_DISABLE_TELEMETRY"=>"yes"}</tt> by default
+	# (for speeding up the command line responses:
+	# {alda-lang/alda#368}[https://github.com/alda-lang/alda/issues/368]).
+	#
+	# When called with an argument +hash+,
+	# merge the old environment variables with +hash+ and set
+	# the merged Hash as the new environment variables.
+	# Returns the new environment variables (a Hash).
+	#
+	# When called with an argument +hash+ and a block,
+	# execute the block with the environment being set to the merge of the old environment
+	# and +hash+, and then restore the old environment.
+	# Returns the returned value of the block.
+	def env hash = nil, &block
+		if hash
+			@env = (old_env = @env).merge hash.map { |k, v| [k.to_s, v.to_s] }.to_h
+			block ? block.().tap { @env = old_env } : @env
+		else
+			@env
+		end
+	end
+	
+	##
+	# :call-seq:
+	#   pipe(command, *args, **opts) -> IO
+	#   pipe(command, *args, **opts) { |io| ... } -> Object
+	#
+	# Runs +alda+ in command line as a child process and returns the pipe IO
+	# or pass the IO to the block.
+	# See COMMANDS_FOR_VERSIONS for an explanation of +args+ and +opts+.
+	def pipe command, *args, **opts, &block
+		add_option = ->((key, val)) do
+			next unless val
+			args.push "--#{Alda::Utils.snake_to_slug key}"
+			args.push val.to_s unless val == true
+		end
+		# executable
+		args.unshift Alda.executable
+		args.map! &:to_s
+		# options
+		Alda.options.each &add_option
+		# subcommand
+		args.push command.to_s
+		# subcommand options
+		opts.each &add_option
+		# subprocess
+		spawn_options = Alda::Utils.win_platform? ? { new_pgroup: true } : { pgroup: true }
+		IO.popen Alda.env, args, **spawn_options, &block
+	end
+	
+	##
+	# :call-seq:
+	#   processes() -> Array
+	#
+	# Returns a Array of details about running \Alda processes.
+	# Only available for \Alda 2.
+	# Each element in the Array is a Hash,
+	# and each Hash has the following keys:
+	# - +:id+: the player-id of the process, a three-letter String.
+	# - +:port+: the port number of the process, an Integer.
+	# - +:state+: the state of the process, a Symbol (may be +nil+, +:ready+, +:active+, or +:starting+).
+	# - +:expiry+: a human-readable description of expiry time of the process, a String (may be +nil+).
+	# - +:type+: the type of the process, a Symbol (may be +:player+ or +:repl_server+).
+	def processes
+		raise GenerationError.new [:v2] if v1?
+		Alda.ps.lines(chomp: true)[1..].map do |line|
+			id, port, state, expiry, type = line.split ?\t
+			port = port.to_i
+			state = state == ?- ? nil : state.to_sym
+			expiry = nil if expiry == ?-
+			type = Alda::Utils.slug_to_snake type
+			{ id: id, port: port, state: state, expiry: expiry, type: type }
+		end
+	end
 	
 	##
 	# :call-seq:
 	#   up?() -> true or false
 	#
 	# Whether the alda server is up.
+	# Checks whether there are any play processes in ::processes in \Alda 2.
 	def up?
-		status.include? 'up'
+		Alda.v1? ? Alda.status.include?('up') : Alda.processes.any? { _1[:type] == :player }
 	end
 	
 	##
@@ -130,10 +261,22 @@ module Alda
 	#   down? -> true or false
 	#
 	# Whether the alda server is down.
+	# Checks whether there are no play processes in ::processes in \Alda 2.
 	def down?
-		status.include? 'down'
+		Alda.v1? ? Alda.status.include?('down') : Alda.processes.none? { _1[:type] == :player }
+	end
+	
+	##
+	# :call-seq:
+	#   deduce_generation -> one of Alda::GENERATIONS
+	#
+	# Deduce the generation of \Alda being used by running <tt>alda version</tt> in command line,
+	# and then set ::generation accordingly.
+	def deduce_generation
+		/(?<major>\d+)\.(?<minor>\d+)\.(?<patch>\d+)/ =~ Alda.version
+		@generation = major == '1' ? :v1 : :v2
 	end
 	
-	module_function :up?, :down?, *COMMANDS
+	module_function :env, :pipe, :processes, :up?, :down?, :deduce_generation
 	
 end

data/lib/alda-rb/error.rb

@@ -9,33 +9,116 @@ class Alda::CommandLineError < StandardError
 	
 	##
 	# The port on which the problematic alda server runs.
+	# This is only available for \Alda 1.
 	#
 	#   begin
 	#     Alda[port: 1108].play code: 'y'
 	#   rescue CommandLineError => e
 	#     e.port # => 1108
 	#   end
-	attr_reader :port
+	def port
+		Alda::GenerationError.assert_generation [:v1]
+		@port
+	end
 	
 	##
 	# :call-seq:
 	#   new(status, msg=nil) -> Alda::CommandLineError
 	#
 	# Create a Alda::CommandLineError object.
-	# +status+ is the status of the process running +alda+ command.
-	# +msg+ is output of +alda+ command. port# info is extracted from +msg+.
+	# +status+ is the status of the process running +alda+ command (can be nil).
+	# +msg+ is the output of +alda+ command. #port info is extracted from +msg+ in \Alda 1.
 	def initialize status, msg = nil
-		if match = msg&.match(/^\[(?<port>\d+)\]\sERROR\s(?<message>.*)$/)
-			super match[:message]
-			@port = match[:port].to_i
+		if Alda.v1? && msg && /^\[(?<port>\d+)\]\sERROR\s(?<message>.*)$/ =~ msg
+			super message
+			@port = port.to_i
 		else
 			super msg
-			@port = nil
 		end
 		@status = status
 	end
 end
 
+##
+# The error is raised when the \Alda nREPL server returns problems.
+# This is only available for \Alda 2.
+# See Alda::REPL#message.
+class Alda::NREPLServerError < StandardError
+	
+	##
+	# The hostname of the nREPL server.
+	attr_reader :host
+	
+	##
+	# The port of the nREPL server.
+	attr_reader :port
+	
+	##
+	# The problems returned by the nREPL server.
+	# This is an Array of String.
+	attr_reader :problems
+	
+	##
+	# The status returned by the nREPL server.
+	# It is an Array of Symbol.
+	# Symbols must appear are +:done+, +:error+, and there may be +:unknown_op+.
+	attr_reader :status
+	
+	##
+	# :call-seq:
+	#   new(host, port, problems, status) -> Alda::NREPLServerError
+	#
+	# Creates a Alda::NREPLServerError object.
+	# Raises Alda::GenerationError if the current generation is not \Alda 2.
+	def initialize host, port, problems, status
+		Alda::GenerationError.assert_generation [:v2]
+		@status = status.map { Alda::Utils.slug_to_snake _1 }
+		if @status.include? :unknown_op
+			super 'unknown operation'
+		else
+			super problems.join ?\n
+		end
+		@host = host
+		@port = port
+		@problems = problems
+	end
+end
+
+##
+# This error is raised when one tries to run commands that are not available for the generation
+# of \Alda specified by Alda::generation.
+#
+#   Alda.v1!
+#   Alda.import # (GenerationError)
+class Alda::GenerationError < StandardError
+	
+	##
+	# The actual generation that was set by Alda::generation when the error occurs.
+	attr_reader :generation
+	
+	##
+	# The generations that could have been set to avoid the error.
+	# An Array.
+	attr_reader :fine_generations
+	
+	##
+	# :call-seq:
+	#   new(fine_generations) -> Alda::GenerationError
+	#
+	# Creates a Alda::GenerationError object.
+	def initialize fine_generations
+		super "bad Alda generation for this action; good ones are #{fine_generations}"
+		@generation = Alda.generation
+		@fine_generations = fine_generations
+	end
+	
+	##
+	# Raises an Alda::GenerationError if the current generation is not in +fine_generations+.
+	def self.assert_generation fine_generations
+		raise new fine_generations unless fine_generations.include? Alda.generation
+	end
+end
+
 ##
 # This error is raised when one tries to
 # append events in an Alda::EventList in a wrong order.
@@ -49,8 +132,7 @@ class Alda::OrderError < StandardError
 	
 	##
 	# The expected element gotten if it is of the correct order.
-	#
-	# See #got
+	# See #got.
 	#
 	#   Alda::Score.new do
 	#     motif = f4 f e e d d c2
@@ -72,6 +154,8 @@ class Alda::OrderError < StandardError
 	##
 	# :call-seq:
 	#   new(expected, got) -> Alda::OrderError
+	#
+	# Creates a Alda::OrderError object.
 	def initialize expected, got
 		super 'events are out of order'
 		@expected = expected