Merge pull request #722 from interscript/reverse

Reversibility

Author: webdev778

README.adoc

@@ -108,6 +108,27 @@ It is then easy to see the exact differences in rendering between the systems.
 diff bgnpcgn-rus-Latn.txt bas-rus-Latn.txt
 ----
 
+You can also run some maps in reverse (warning: not all maps are made to be reversed),
+either by changing an order of character sets in a name (for bas-rus-`Cyrl-Latn`-2017-bss
+it would be bas-rus-`Latn-Cyrl`-2017-bss) or appending `-reverse` to their name:
+
+[source,sh]
+----
+interscript my_jamos.txt \
+  --system=var-kor-Hang-Hang-jamo-reverse \
+  --output=my_hangul.txt
+----
+
+You can also compose some maps, by joining their names with `|` (similar to how bash
+pipe works). For instance:
+
+[source,sh]
+----
+interscript my_file.txt \
+  --system='var-map1-Xxxx-Xxxx|var-map2-Xxxx-Xxxx' \
+  --output=my_output.txt
+----
+
 If you use Interscript from the Git repository, you would call the following command
 instead of `interscript`:
 

docs/Integration_with_Ruby_Applications.adoc

@@ -70,3 +70,16 @@ output = Interscript.transliterate("bas-rus-Cyrl-Latn-2017-bss",
                                    cache,
                                    compiler: Interscript::Compiler::Ruby)
 ----
+
+=== Transliterating in reverse
+
+To reverse a given string using a map with a name of a form:
+`bas-rus-Cyrl-Latn-2017-bss`, change places for Cyrl and Latn.
+
+To reverse a given string using a map with a name of a form:
+`var-swe-Latn-Latn-2021`, append `-reverse` to its name.
+
+Please note: this only works for Ruby implementation. Other implementations
+depend on the Ruby implementation for the purpose of compilation. For those,
+you need to compile the map using the Ruby implementation, but the name has
+to be given according to the above hint.

docs/Interscript_Map_Format.adoc

@@ -418,6 +418,47 @@ stage {
 When ran against a string `"abcde"`, this stage will produce an output of
 `"[a][b][c]de"`.
 
+== Reversibility
+
+Starting with Interscript 2.2 we added reversibility support. In general all
+commands, except for metadata (and tests - for now) support a `reverse_run`
+keyword. This keyword is `nil` by default, which means, that it's reversible.
+(One exception though: `sub` call, if given a `none` as `to`, defaults to
+`reverse_run: false`).
+
+`reverse_run: false` means, that the command is only ran in forward.
+`reverse_run: true`, on the other hand, means that the command is only ran in
+reverse.
+
+Example 1:
+
+[source,ruby]
+----
+stage {
+  sub "a", "b", reverse_run: true
+  sub "c", "d", reverse_run: false
+}
+----
+
+When ran in forward mode (normal run) on a string "abcde", it gives "abdde".
+When ran in reverse mode on a string "abcde", it gives "aacde".
+
+Example 2:
+
+[source,ruby]
+----
+stage {
+  parallel {
+    sub "a", "あ"
+    sub "o", "お"
+    sub "i", "い"
+  }
+}
+----
+
+When ran in forward mode (normal run) on a string "あおい", it gives "aoi".
+When ran in reverse more on a string "aoi", it gives "あおい".
+
 == Ending notes
 
 This document described everything Interscript currently supports, but it is

ruby/Gemfile

@@ -26,4 +26,6 @@ unless ENV["SKIP_JS"]
   end
 end
 
+gem 'pry'
+
 gem 'simplecov', require: false, group: :test

ruby/bin/console

@@ -3,12 +3,8 @@
 require "bundler/setup"
 require "interscript"
 
-# You can add fixtures and/or initialization code here to make experimenting
-# with your gem easier. You can also use a different console, if you like.
+require "interscript/utils/helpers"
+include Interscript::Utils::Helpers
 
-# (If you use this, don't forget to add pry to your Gemfile!)
-# require "pry"
-# Pry.start
-
-require "irb"
-IRB.start(__FILE__)
+require "pry"
+Pry.start

ruby/lib/interscript/compiler/javascript.rb

@@ -53,6 +53,7 @@ def parallel_regexp_compile(subs_hash)
 
   def compile_rule(r, map = @map, wrapper = false)
     c = ""
+    return c if r.reverse_run == true
     case r
     when Interscript::Node::Stage
       c += "map.stages.#{r.name} = function(s) {\n"
@@ -75,6 +76,7 @@ def compile_rule(r, map = @map, wrapper = false)
           raise ArgumentError, "Can't parallelize rules with :not_before" if i.not_before
           raise ArgumentError, "Can't parallelize rules with :not_after" if i.not_after
 
+          next if i.reverse_run == true
           a << [compile_item(i.from, map, :par), compile_item(i.to, map, :parstr)]
         end
         ah = a.hash.abs
@@ -88,7 +90,8 @@ def compile_rule(r, map = @map, wrapper = false)
         a = []
         Interscript::Stdlib.deterministic_sort_by_max_length(r.children).each do |i|
           raise ArgumentError, "Can't parallelize #{i.class}" unless Interscript::Node::Rule::Sub === i
-
+          
+          next if i.reverse_run == true
           a << [build_regexp(i, map), compile_item(i.to, map, :parstr)]
         end
         ah = a.hash.abs
@@ -102,6 +105,8 @@ def compile_rule(r, map = @map, wrapper = false)
       from = %{"#{build_regexp(r, map).gsub("/", "\\\\/")}"}
       if r.to == :upcase
         to = 'function(a){return a.toUpperCase();}'
+      elsif r.to == :downcase
+        to = 'function(a){return a.toLowerCase();}'
       else
         to = compile_item(r.to, map, :str)
       end

ruby/lib/interscript/compiler/ruby.rb

@@ -42,6 +42,7 @@ def compile(map, debug: false)
 
   def compile_rule(r, map = @map, wrapper = false)
     c = ""
+    return c if r.reverse_run == true
     case r
     when Interscript::Node::Stage
       c += "Interscript::Maps.add_map_stage \"#{@map.name}\", #{r.name.inspect} do |s|\n"
@@ -65,6 +66,7 @@ def compile_rule(r, map = @map, wrapper = false)
           raise ArgumentError, "Can't parallelize rules with :not_before" if i.not_before
           raise ArgumentError, "Can't parallelize rules with :not_after" if i.not_after
 
+          next if i.reverse_run == true
           a << [compile_item(i.from, map, :par), compile_item(i.to, map, :parstr)]
         end
         ah = a.hash.abs
@@ -79,6 +81,7 @@ def compile_rule(r, map = @map, wrapper = false)
         Interscript::Stdlib.deterministic_sort_by_max_length(r.children).each do |i|
           raise ArgumentError, "Can't parallelize #{i.class}" unless Interscript::Node::Rule::Sub === i
 
+          next if i.reverse_run == true
           a << [build_regexp(i, map), compile_item(i.to, map, :parstr)]
         end
         ah = a.hash.abs
@@ -92,6 +95,8 @@ def compile_rule(r, map = @map, wrapper = false)
       from = "/#{build_regexp(r, map).gsub("/", "\\\\/")}/"
       if r.to == :upcase
         to = '&:upcase'
+      elsif r.to == :downcase
+        to = '&:downcase'
       else
         to = compile_item(r.to, map, :str)
       end

ruby/lib/interscript/dsl.rb

@@ -2,12 +2,45 @@
 
 module Interscript::DSL
   @cache = {}
-  def self.parse(map_name)
+  def self.parse(map_name, reverse: true)
     # map name aliases? here may be a place to wrap it
 
     return @cache[map_name] if @cache[map_name]
-    path = Interscript.locate(map_name)
+
+    # This is a composition, so let's make a new virtual map
+    # that calls all maps in a sequence.
+    if map_name.include? "|"
+      map_parts = map_name.split("|").map(&:strip)
+
+      doc = Interscript::DSL::Document.new(map_name) do
+        map_parts.each_with_index do |i, idx|
+          dependency i, as: :"part#{idx}"
+        end
+
+        stage {
+          map_parts.each_with_index do |i, idx|
+            run map[:"part#{idx}"].stage.main
+          end
+        }
+      end.node
+
+      return @cache[map_name] = doc
+    end
+
+    path = begin
+      Interscript.locate(map_name)
+    rescue Interscript::MapNotFoundError => e
+      # But maybe we called the map in a reversed fashion?
+      begin
+        raise e if reverse == false # Protect from an infinite loop
+        reverse_name = Interscript::Node::Document.reverse_name(map_name)
+        return @cache[map_name] = parse(reverse_name, reverse: false).reverse
+      rescue Interscript::MapNotFoundError
+        raise e
+      end
+    end
     library = path.end_with?(".iml")
+
     map_name = File.basename(path, ".imp")
     map_name = File.basename(map_name, ".iml")
 

ruby/lib/interscript/dsl/group.rb

@@ -8,23 +8,24 @@ def initialize(&block)
     self.instance_exec(&block)
   end
 
-  def run(stage)
+  def run(stage, **kwargs)
     if stage.class != Interscript::Node::Item::Stage
       raise TypeError, "I::Node::Item::Stage expected, got #{stage.class}"
     end
-    @node.children << Interscript::Node::Rule::Run.new(stage)
+    @node.children << Interscript::Node::Rule::Run.new(stage, **kwargs)
   end
 
   def sub(from, to, **kwargs, &block)
-    puts "sub(#{from.inspect},#{to}, kargs = #{
-      kargs.inspect
+    puts "sub(#{from.inspect},#{to}, kwargs = #{
+      kwargs.inspect
     }) from #{self.inspect}" if $DEBUG
 
     rule = Interscript::Node::Rule::Sub.new(from, to, **kwargs)
     @node.children << rule
   end
 
   def upcase; :upcase; end
+  def downcase; :downcase; end
 
   Interscript::Stdlib.available_functions.each do |fun|
     define_method fun do |**kwargs|
@@ -35,9 +36,9 @@ def upcase; :upcase; end
     end
   end
 
-  def parallel(&block)
+  def parallel(**kwargs, &block)
     puts "parallel(#{chars.inspect}) from #{self.inspect}" if $DEBUG
-    group = Interscript::DSL::Group::Parallel.new(&block)
+    group = Interscript::DSL::Group::Parallel.new(**kwargs, &block)
     @node.children << group.node
   end
 end

ruby/lib/interscript/dsl/group/parallel.rb

@@ -1,6 +1,6 @@
 class Interscript::DSL::Group::Parallel < Interscript::DSL::Group
-  def initialize(&block)
-    @node = Interscript::Node::Group::Parallel.new
+  def initialize(reverse_run: nil, &block)
+    @node = Interscript::Node::Group::Parallel.new(reverse_run: reverse_run)
     self.instance_exec(&block)
   end
 end