alda-rb 0.2.1 → 0.3.0

data/lib/alda-rb/repl.rb

@@ -1,17 +1,10 @@
 require 'colorize'
 require 'irb/ruby-lex'
 require 'json'
-require 'readline'
+require 'reline'
 require 'stringio'
-
-##
-# :call-seq:
-#   repl() -> nil
-#
-# Start a REPL session.
-def Alda.repl
-	Alda::REPL.new.run
-end
+require 'bencode'
+require 'socket'
 
 ##
 # An instance of this class is an \REPL session.
@@ -32,101 +25,303 @@ end
 # your previous input, run <tt>puts history</tt>.
 #
 # Unlike \IRB, this \REPL does not print the result of
-# the executed codes. Use +p+ if you want.
+# the executed codes. Use +p+ or +puts+ if you want.
 #
 # +Interrupt+ and +SystemExit+ exceptions are rescued and
 # will not cause the process terminating.
 # +exit+ terminates the \REPL session instead of the process.
 #
-# To start an \REPL session in a ruby program, use Alda::repl.
+# To start an \REPL session in a ruby program, use #run.
 # To start an \REPL session conveniently from command line,
-# run command <tt>ruby -ralda-rb -e "Alda.repl"</tt>.
+# run command <tt>alda-irb</tt>.
+# For details about this command line tool, run <tt>alda-irb --help</tt>.
 #
-#   $ ruby -ralda-rb -e "Alda.repl"
-#   > puts status
-#   [27713] Server up (2/2 workers available, backend port: 33245)
-#   > piano_ c d e f
-#   [piano: c d e f]
+#   $ alda-irb
+#   > p processes.last
+#   {:id=>"dus", :port=>34317, :state=>nil, :expiry=>nil, :type=>:repl_server}
+#   > piano_; c d e f
+#   piano: [c d e f]
 #   > 5.times do
-#   > c
-#   > end
+#   .   c
+#   >   end
 #   c c c c c
-#   > puts history
-#   [piano: c d e f]
+#   > score_text
+#   piano: [c d e f]
 #   c c c c c
 #   > play
+#   Playing...
 #   > save 'temp.alda'
 #   > puts `cat temp.alda`
-#   [piano: c d e f]
+#   piano: [c d e f]
 #   c c c c c
 #   > system 'rm temp.alda'
 #   > exit
+#
+# Notice that there is a significant difference between \Alda 1 \REPL and \Alda 2 \REPL.
+# In short, \Alda 2 has a much more powerful \REPL than \Alda 1,
+# so it dropped the <tt>--history</tt> option in the <tt>alda play</tt> command line interface
+# ({alda-lang/alda#367}[https://github.com/alda-lang/alda/issues/367]).
+# It has an nREPL server, and this class simply functions by sending messages to the nREPL server.
+# However, for \Alda 1, this class maintains necessary information
+# in the memory of the Ruby program,
+# and the \REPL is implemented by repeatedly running <tt>alda play</tt> in command line.
+# Therefore, this class functions differently for \Alda 1 and \Alda 2
+# and you thus should not modify Alda::generation during an \REPL session.
+#
+# It is also possible to use this class as a Ruby wrapper of APIs of the \Alda nREPL server
+# in \Alda 2.
+# In this usage, you never need to call #run, and you call #message or #raw_message instead.
+#
+#   repl = Alda::REPL.new
+#   repl.message :eval_and_play, code: 'piano: c d e f' # => nil
+#   repl.message :eval_and_play, code: 'g a b > c' # => nil
+#   repl.message :score_text # => "piano: [c d e f]\ng a b > c\n"
+#   repl.message :eval_and_play, code: 'this will cause an error' # (raises Alda::NREPLServerError)
 class Alda::REPL
 	
 	##
 	# The score object used in Alda::REPL.
 	#
 	# Includes Alda, so it can refer to alda commandline.
+	# However, the methods Alda::Score#play, Alda::Score#parse and Alda::Score#export
+	# are still retained instead of being overridden by the included module.
 	#
 	# When you are in an \REPL session, you are actually
 	# in an instance of this class,
 	# so you can call the instance methods down here
 	# when you play with an \REPL.
-	class TempScore < Alda::Score
+	class TempScore < ::Alda::Score
 		include Alda
 		
-		Score.instance_methods(false).each do |meth|
-			define_method meth, Score.instance_method(meth)
+		%i[play parse export].each do |meth|
+			define_method meth, Alda::Score.instance_method(meth)
 		end
 		
+		##
+		# :call-seq:
+		#   new(session) -> TempScore
+		#
+		# Creates a new TempScore for the given \REPL session specified by +session+.
+		# It is called in Alda::REPL::new.
 		def initialize session
 			super()
 			@session = session
 		end
 		
+		##
+		# :call-seq:
+		#   to_s -> String
+		#
+		# Overrides Alda::Score#to_s.
+		# Returns the history.
+		#
+		#   $ alda-irb
+		#   > harmonica_; a b c
+		#   harmonica: [a b c]
+		#   > guitar_; c g e
+		#   guitar: [c g e]
+		#   > p to_s
+		#   "harmonica: [a b c]\nguitar: [c g e]\n"
 		def to_s
-			history
-		end
-		
-		def history
-			@session.history.to_s
+			@session.history
 		end
 		
+		##
+		# :call-seq:
+		#   clear_history() -> nil
+		#
+		# Clears all the modifications that have been made to the score
+		# and start a new one.
+		# See #score for an example.
 		def clear_history
 			@session.clear_history
 		end
+		alias new clear_history
+		alias new_score clear_history
 		
+		##
+		# :call-seq:
+		#   get_binding() -> Binding
+		#
+		# Returns a Binding for the instance eval local environment of this score.
+		# Different callings of this method will return different bindings,
+		# and they do not share local variables.
+		# This method is called in Alda::REPL::new.
+		#
+		#   $ alda-irb
+		#   > p get_binding.receiver == self
+		#   true
 		def get_binding
 			binding
 		end
 		
+		##
+		# :call-seq:
+		#   score() -> nil
+		#
+		# Print the history (all \Alda code of the score).
+		#
+		#   $ alda-irb
+		#   > violin_; a b
+		#   violin: [a b]
+		#   > score
+		#   violin: [a b]
+		#   > clear_history
+		#   > score
+		#   > viola_; c
+		#   viola: c
+		#   > score
+		#   viola: c
 		def score
-			puts history
+			print @session.color ? @session.history.blue : @session.history
+			nil
 		end
+		alias score_text score
 		
+		##
+		# :call-seq:
+		#   map() -> nil
+		#
+		# Prints a data representation of the score.
+		# This is the output that you get when you call Alda::Score#parse.
 		def map
-			puts JSON.generate JSON.parse(parse),
-			                   indent: '  ', space: ' ', object_nl: ?\n, array_nl: ?\n
+			json = Alda.v1? ? parse : @session.message(:score_data)
+			json = JSON.generate JSON.parse(json), indent: '  ', space: ' ', object_nl: ?\n, array_nl: ?\n
+			puts @session.color ? json.blue : json
+		end
+		alias score_data map
+		
+		##
+		# :call-seq:
+		#   score_events() -> nil
+		#
+		# Prints the parsed events output of the score.
+		# This is the output that you get when you call Alda::Score#parse with <tt>output: :events</tt>.
+		def score_events
+			json = Alda.v1? ? parse(output: :events) : @session.message(:score_events)
+			json = JSON.generate JSON.parse(json), indent: '  ', space: ' ', object_nl: ?\n, array_nl: ?\n
+			puts @session.color ? json.blue : json
 		end
 		
 		alias quit exit
-		alias new clear_history
 	end
 	
 	##
-	# The history.
-	attr_reader :history
+	# The host of the nREPL server. Only useful in \Alda 2.
+	attr_reader :host
+	
+	##
+	# The port of the nREPL server. Only useful in \Alda 2.
+	attr_reader :port
+	
+	##
+	# Whether the output should be colored.
+	attr_accessor :color
+	
+	##
+	# Whether a preview of what \Alda code will be played everytime you input ruby codes.
+	attr_accessor :preview
 	
 	##
 	# :call-seq:
-	#   new() -> Alda::REPL
+	#   new(**opts) -> Alda::REPL
 	#
 	# Creates a new Alda::REPL.
-	def initialize
+	# The parameter +color+ specifies whether the output should be colored (sets #color).
+	# The parameter +preview+ specifies whether a preview of what \Alda code will be played
+	# everytime you input ruby codes (sets #preview).
+	#
+	# The +opts+ are passed to the command line of <tt>alda repl</tt>.
+	# Available options are +host+, +port+, etc.
+	# Run <tt>alda repl --help</tt> for more info.
+	# If +port+ is specified and +host+ is not or is specified to be <tt>"localhost"</tt>
+	# or <tt>"127.0.0.1"</tt>, then this method will try to connect to an existing
+	# \Alda REPL server.
+	# A new one will be started only if no existing server is found.
+	#
+	# The +opts+ are ignored in \Alda 1.
+	def initialize color: true, preview: true, **opts
 		@score = TempScore.new self
 		@binding = @score.get_binding
 		@lex = RubyLex.new
-		@history = StringIO.new
+		@color = color
+		@preview = preview
+		setup_repl opts
+	end
+	
+	##
+	# :call-seq:
+	#   setup_repl(opts) -> nil
+	#
+	# Sets up the \REPL session.
+	# This method is called in ::new.
+	# After you #terminate the session,
+	# you cannot use the \REPL anymore unless you call this method again.
+	def setup_repl opts
+		if Alda.v1?
+			@history = StringIO.new
+		else
+			if opts[:port] && [nil, 'localhost', '127.0.0.1'].include?(opts[:host]) &&
+			   Alda.processes.any? { _1[:port] == opts[:port].to_i && _1[:type] == :repl_server }
+				@port = opts[:port].to_i
+				@host = opts[:host] || 'localhost'
+			else
+				@nrepl_pipe = Alda.pipe :repl, **opts, server: true
+				/nrepl:\/\/(?<host>[a-zA-Z0-9._\-]+):(?<port>\d+)/ =~ @nrepl_pipe.gets
+				@host = host
+				@port = port.to_i
+				Process.detach @nrepl_pipe.pid
+			end
+			@socket = TCPSocket.new @host, @port
+			@bencode_parser = BEncode::Parser.new @socket
+		end
+		nil
+	end
+	
+	##
+	# :call-seq:
+	#   raw_message(contents) -> Hash
+	#
+	# Sends a message to the nREPL server and returns the response.
+	# The parameter +contents+ is a Hash or a JSON string.
+	#
+	#   repl = Alda::REPL.new
+	#   repl.raw_message op: 'describe' # => {"ops"=>...}
+	def raw_message contents
+		Alda::GenerationError.assert_generation [:v2]
+		contents = JSON.parse contents if contents.is_a? String
+		@socket.write contents.bencode
+		@bencode_parser.parse!
+	end
+	
+	##
+	# :call-seq:
+	#   message(op, **params) -> String or Hash
+	#
+	# Sends a message to the nREPL server with the following format,
+	# with +op+ being the operation name (the +op+ field in the message),
+	# and +params+ being the parameters (other fields in the message).
+	# Then, this method analyzes the response.
+	# If there is an error, raises Alda::NREPLServerError.
+	# Otherwise, if the response contains only one field, return the content of that field (a String).
+	# Otherwise, return the whole response as a Hash.
+	#
+	#   repl = Alda::REPL.new
+	#   repl.message :eval_and_play, code: 'piano: c d e f' # => nil
+	#   repl.message :eval_and_play, code: 'g a b > c' # => nil
+	#   repl.message :score_text # => "piano: [c d e f]\ng a b > c\n"
+	#   repl.message :eval_and_play, code: 'this will cause an error' # (raises Alda::NREPLServerError)
+	def message op, **params
+		result = raw_message op: Alda::Utils.snake_to_slug(op), **params
+		result.transform_keys! { Alda::Utils.slug_to_snake _1 }
+		if result.delete(:status).include? 'error'
+			raise Alda::NREPLServerError.new @host, @port, result.delete(:problems)
+		end
+		case result.size
+		when 0 then nil
+		when 1 then result.values.first
+		else result
+		end
 	end
 	
 	##
@@ -134,10 +329,11 @@ class Alda::REPL
 	#   run() -> nil
 	#
 	# Runs the session.
-	# Includes the start, the main loop, and the termination.
+	# Includes the start (#start), the main loop, and the termination (#terminate).
 	def run
 		start
 		while code = rb_code
+			next if code.empty?
 			break unless process_rb_code code
 		end
 		terminate
@@ -159,18 +355,37 @@ class Alda::REPL
 	# It can intelligently continue reading if the code is not complete yet.
 	def rb_code
 		result = ''
+		indent = 0
 		begin
-			buf = Readline.readline '> '.green, true
-			return unless buf
-			result.concat buf, ?\n
+			result.concat readline(indent).tap { return unless _1 }, ?\n
 			ltype, indent, continue, block_open = @lex.check_state result
 		rescue Interrupt
 			$stdout.puts
-			retry
+			return ''
 		end while ltype || indent.nonzero? || continue || block_open
 		result
 	end
 	
+	##
+	# :call-seq:
+	#   readline(indent = 0) -> String
+	#
+	# Prompts the user to input a line.
+	# The parameter +indent+ is the indentation level.
+	# Twice the number of spaces is already in the input field before the user fills in.
+	# The prompt hint is different for zero +indent+ and nonzero +indent+.
+	# Returns the user input.
+	def readline indent = 0
+		prompt = indent.nonzero? ? '. ' : '> '
+		prompt = prompt.green if @color
+		Reline.pre_input_hook = -> do
+			Reline.insert_text '  ' * indent
+			Reline.redisplay
+			Reline.pre_input_hook = nil
+		end
+		Reline.readline prompt, true
+	end
+	
 	##
 	# :call-seq:
 	#   process_rb_code(code) -> true or false
@@ -182,18 +397,16 @@ class Alda::REPL
 		@score.clear
 		begin
 			@binding.eval code
-		rescue StandardError, ScriptError => e
+		rescue StandardError, ScriptError, Interrupt => e
 			$stderr.print e.full_message
 			return true
-		rescue Interrupt
-			return true
 		rescue SystemExit
 			return false
 		end
 		code = @score.events_alda_codes
 		unless code.empty?
-			$stdout.puts code.yellow
-			play_score code
+			$stdout.puts @color ? code.yellow : code
+			try_command { play_score code }
 		end
 		true
 	end
@@ -202,12 +415,15 @@ class Alda::REPL
 	# :call-seq:
 	#   try_command() { ... } -> obj
 	#
-	# Tries to run the block and rescue Alda::CommandLineError.
+	# Run the block.
+	# In \Alda 1, catches Alda::CommandLineError.
+	# In \Alda 2, catches Alda::NREPLServerError.
+	# If an error is caught, prints the error message (in red if #color is true).
 	def try_command
 		begin
 			yield
-		rescue Alda::CommandLineError => e
-			puts e.message.red
+		rescue Alda.v1? ? Alda::CommandLineError : Alda::NREPLServerError => e
+			puts @color ? e.message.red : e.message
 		end
 	end
 	
@@ -215,11 +431,15 @@ class Alda::REPL
 	# :call-seq:
 	#   play_score(code) -> nil
 	#
-	# Plays the score by sending +code+ to command line alda.
+	# Appends +code+ to the history and plays the +code+ as \Alda code.
+	# In \Alda 1, plays the score by sending +code+ to command line alda.
+	# In \Alda 2, sends +code+ to the nREPL server for evaluating and playing.
 	def play_score code
-		try_command do
+		if Alda.v1?
 			Alda.play code: code, history: @history
 			@history.puts code
+		else
+			message :eval_and_play, code: code
 		end
 	end
 	
@@ -228,18 +448,50 @@ class Alda::REPL
 	#   terminate() -> nil
 	#
 	# Terminates the REPL session.
-	# Currently just clears #history.
+	# In \Alda 1, just calls #clear_history.
+	# In \Alda 2, sends a SIGINT to the nREPL server if it was spawned by the Ruby program.
 	def terminate
-		clear_history
+		if Alda.v1?
+			clear_history
+		else
+			if @nrepl_pipe
+				if Alda::Utils.win_platform?
+					system 'taskkill', '/f', '/pid', @nrepl_pipe.pid.to_s
+				else
+					Process.kill :INT, @nrepl_pipe.pid
+				end
+				@nrepl_pipe.close
+			end
+			@socket.close
+		end
+	end
+	
+	##
+	# :call-seq:
+	#   history() -> String
+	#
+	# In \Alda 1, it is the same as an attribute reader.
+	# In \Alda 2, it asks the nREPL server for its score text and returns it.
+	def history
+		if Alda.v1?
+			@history
+		else
+			try_command { message :score_text }
+		end
 	end
 	
 	##
 	# :call-seq:
 	#   clear_history() -> nil
 	#
-	# Clears #history.
+	# In \Alda 1, clears #history.
+	# In \Alda 2, askes the nREPL server to clear its history (start a new score).
 	def clear_history
-		@history = StringIO.new
+		if Alda.v1?
+			@history = StringIO.new
+		else
+			try_command { message :new_score }
+		end
 		nil
 	end
 end

data/lib/alda-rb/utils.rb

@@ -0,0 +1,47 @@
+##
+# Some useful functions.
+module Alda::Utils
+	
+	##
+	# :call-seq:
+	#   warn(message) -> nil
+	#
+	# Prints a warning message to standard error, appended by a newline.
+	# The message is prefixed with the filename and lineno of the caller
+	# (the lowest level where the file is not an alda-rb source file).
+	def warn message
+		location = caller_locations.find { !_1.path.start_with? __dir__ }
+		Warning.warn "#{location.path}:#{location.lineno}: #{message}\n"
+	end
+	
+	##
+	# :call-seq:
+	#   win_platform? -> true or false
+	#
+	# Returns whether the current platform is Windows.
+	def win_platform?
+		Gem.win_platform?
+	end
+	
+	##
+	# :call-seq:
+	#   snake_to_slug(sym) -> String
+	#
+	# Converts a snake_case Symbol to a slug-case String.
+	# The inverse of ::slug_to_snake.
+	def snake_to_slug sym
+		sym.to_s.gsub ?_, ?-
+	end
+	
+	##
+	# :call-seq:
+	#   slug_to_snake(str) -> Symbol
+	#
+	# Converts a slug-case String to a snake_case Symbol.
+	# The inverse of ::snake_to_slug.
+	def slug_to_snake str
+		str.to_s.gsub(?-, ?_).to_sym
+	end
+	
+	module_function :warn, :win_platform?, :snake_to_slug, :slug_to_snake
+end

data/lib/alda-rb/version.rb

@@ -7,5 +7,5 @@ module Alda
 	# The version number of alda-rb.
 	#
 	# The same as that in alda-rb gem spec.
-	VERSION = '0.2.1'
+	VERSION = '0.3.0'
 end

data/lib/alda-rb.rb

@@ -2,6 +2,7 @@
 
 require 'alda-rb/version'
 require 'alda-rb/patches'
+require 'alda-rb/utils'
 require 'alda-rb/error'
 require 'alda-rb/commandline'
 require 'alda-rb/event_list'

metadata

@@ -1,26 +1,30 @@
 --- !ruby/object:Gem::Specification
 name: alda-rb
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.3.0
 platform: ruby
 authors:
 - Ulysses Zhan
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2020-08-13 00:00:00.000000000 Z
+date: 2023-05-30 00:00:00.000000000 Z
 dependencies: []
 description: 
 email:
 - UlyssesZhan@gmail.com
-executables: []
+executables:
+- alda-irb
 extensions: []
 extra_rdoc_files: []
 files:
+- ".github/workflows/main.yml"
 - ".gitignore"
 - ".travis.yml"
+- CHANGELOG.md
 - CODE_OF_CONDUCT.md
 - Gemfile
+- Gemfile.lock
 - LICENSE.txt
 - README.md
 - Rakefile
@@ -31,10 +35,12 @@ files:
 - examples/bwv846_prelude.rb
 - examples/clapping_music.rb
 - examples/dot_accessor.rb
+- examples/dynamics.rb
 - examples/entropy.rb
 - examples/hanon.rb
 - examples/hello_world.rb
 - examples/key_signature.rb
+- examples/marriage_d_amour.rb
 - examples/midi_note_numbers.rb
 - examples/modes2.rb
 - examples/multi_poly.rb
@@ -42,7 +48,10 @@ files:
 - examples/phase.rb
 - examples/seconds_and_milliseconds.rb
 - examples/showcase.rb
+- examples/track-volume.rb
+- examples/variables-2.rb
 - examples/variables.rb
+- exe/alda-irb
 - lib/alda-rb.rb
 - lib/alda-rb/commandline.rb
 - lib/alda-rb/error.rb
@@ -50,14 +59,15 @@ files:
 - lib/alda-rb/event_list.rb
 - lib/alda-rb/patches.rb
 - lib/alda-rb/repl.rb
+- lib/alda-rb/utils.rb
 - lib/alda-rb/version.rb
-homepage: https://github.com/UlyssesZh/alda-rb
+homepage: https://ulysseszh.github.io/doc/alda-rb
 licenses:
 - MIT
 metadata:
-  homepage_uri: https://github.com/UlyssesZh/alda-rb
+  homepage_uri: https://ulysseszh.github.io/doc/alda-rb
   source_code_uri: https://github.com/UlyssesZh/alda-rb
-  changelog_uri: https://github.com/UlyssesZh/alda-rb/releases
+  changelog_uri: https://ulysseszh.github.io/doc/alda-rb/CHANGELOG_md.html
 post_install_message: 
 rdoc_options: []
 require_paths:
@@ -73,7 +83,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.2
+rubygems_version: 3.1.6
 signing_key: 
 specification_version: 4
 summary: A Ruby library for live-coding music with Alda.