windstorm 0.1.0

data/.gitignore

@@ -0,0 +1,5 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*
+

data/Gemfile

@@ -0,0 +1,4 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in hoge.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2012 parrot-studio
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,236 @@
+BF風言語解析器 - Windstorm
+===============
+
+Introduction
+---------------
+BrainF**k（BF）風のソースコード解析と実行をおこなうRubyのGemです。
+定義を作成することで、自由にBF風の言語を構築することができます。
+いわゆる「ネタ言語用解析器」です。
+
+Ruby Version
+---------------
+- Ruby1.9.x以上
+ - CRuby1.9.2/1.9.3でspecが通ることを確認しています
+ - Ruby1.9.xに対応した処理系であれば動くと思われます（JRuby等）
+ - Ruby1.8.xに対応する予定はありません（動くかもしれませんが、一切保証しません）
+
+Source
+---------------
+https://github.com/parrot-studio/windstorm
+
+Installation
+---------------
+    gem install windstorm
+
+Usage
+---------------
+### 概要
+基本的な実行原理はBFと同じです。
+外部から自由に定義を与えることで、自由な解析器を作ることができます。
+
+WindstormはParser/Machine/Executorの3クラスで構成されています。
+
+- Parser   : 与えられた定義を元に、ソースコードを命令の配列に変換する
+- Machine  : 与えられた命令の配列を元に、命令を実行して結果を返す
+- Executor : ParserとMachineを連携させて一つの処理系を構成する
+
+### 命令
+WindstormではBFに存在する8命令を抽象化し、シンボルで定義しています。
+（括弧内は対応するBFの命令語）
+
+- :pinc(>) : ポインタをインクリメントする
+- :pdec(<) : ポインタをデクリメントする
+- :inc (+) : ポインタが指す値をインクリメントする
+- :dec (-) : ポインタが指す値をデクリメントする
+- :out (.) : ポインタが指す値を出力する
+- :inc (,) : 入力から読み込んで、ポインタが指す値を更新する
+- :jmp ([) : ポインタが指す値が0ならば、対応する :ret にジャンプする
+- :ret (]) : ポインタが指す値が0でなければ、対応する :jmp にジャンプする
+
+また、以下の2命令を追加しています。
+
+- :clip  : ポインタが指す値を専用のclipバッファに保存する
+ - 再度呼ばれた場合は、新しい値でclipバッファを上書きする
+- :paste : ポインタが指す値をclipバッファの値で上書きする
+ - 一度も :clip を呼ばれていない場合、0で上書きする
+
+### 定義
+
+10の命令について、対応する文字列をHash形式で指定します
+
+    table = {
+      :pinc => '>',
+      :pdec => '<',
+      :inc => ['+', 'a'], # 複数指定も可能
+      :dec => ['-', 'あ'], # マルチバイトでもOK
+      :out => ['.', '出力'] # 一文字でなくてもOK
+      # 不要な命令は定義しなくても良い
+    }
+    exec = Executor.create_from_table(table)
+
+Executorは外部ファイルからの読み込みに対応しています。
+その場合は定義をYAML形式（UTF-8）で記述します。
+
+    # table.yml
+    :pinc:
+    - '>'
+    :pdec:
+    - '<'
+    :inc:
+    - '+'
+    - 'a'
+    :dec:
+    - '-'
+    - あ
+    :out:
+    - '.'
+    - 出力
+    ########
+    
+    exec = Executor.create_from_file('table.yml')
+
+### ソースコード仕様
+
+- 文字コードはUTF-8で記述してください
+
+- 定義されていない文字列は全て無視します
+ - 定義に重複する文字列があった場合、どちらの命令に変換されるかは不定です
+ - 解析には正規表現を用いていますので、それに依存した動作になります
+
+- '#'か'//'で始まる行はコメントとして扱われます
+ - 空白を含め、一文字でも'#'等の前にあるとコメントになりません
+ - よって、文の途中に'#'等があっても、コメントとして解釈しません
+ - なので、'#'等を定義に含めても、命令として解釈させることが可能です
+
+### Executorによる解析と実行
+
+    # 定義をYAMLファイルから読み込み
+    exec = Executor.create_from_file('table.yml')
+    
+    # 命令に対応する文字列だけを抽出
+    exec.filter('+!+?  出力します  >') #=> ['+', '+', '出力', '>']
+    
+    # 命令に変換した配列を取得
+    exec.build('+!+?  出力します  >') #=> [:inc, :inc, :out, :pinc]
+
+    # 命令を実行
+    source = (['+'] * 33 + ['.']).join
+    exec.execute(source) #=> '!'
+    
+    # デバッグモード（後述）で実行
+    exec.debug_execute(source)
+    
+    # ファイルから読み込んで実行
+    exec.filter_from_file('hello.bf')
+    exec.build_from_file('hello.bf')
+    exec.execute_from_file('hello.bf')
+    exec.debug_execute_from_file('hello.bf')
+
+Executorが中で使っているParser/Machineの詳細は、
+それぞれのspecを参照してください。
+
+### 実行オプション
+
+Executor#executeにはオプションを与えることができます
+
+    exec.execute(source, :debug => true, :size => 10)
+
+- :debug, :loose, :flash : trueを与えると、各モードが有効になります
+- :size : 値を格納するバッファのサイズを指定します
+
+格納バッファサイズのデフォルトは100となっていますが、
+実行時オプションで :size を指定することにより、
+任意のサイズに変更することが可能です。（通常は変更不要）
+
+格納バッファサイズはWindstorm処理系の仮想的な概念で、
+本質的にはRuby処理系のArrayクラス仕様に依存します。
+後述のlooseモードの説明も参照してください。
+
+#### デバッグモード（:debug）
+
+命令を一つ実行するたびに、デバッグ文を出力します。
+
+    # 出力例
+    "step:197 com:out index:43 point:0 buffer:[115, 0] clip:100 result:s"
+
+- step   : 実行ステップ数
+- com    : 実行したコマンド
+- index  : comに対応する命令配列のindex
+- point  : ポインタの値（bufferのindexに対応）
+- buffer : 値の格納バッファ（配列）
+- clip   : clipバッファに保存されている値
+- result : :out で出力した結果
+
+出力先はRuby処理系の$stdoutが指すIOオブジェクトです。
+通常は実行しているコンソールになります。
+
+#### strictモードとlooseモード（:loose）
+
+Windstormでソースを実行する目的は、
+最終的に「何らかの文字列の出力すること」です。
+
+そのため、デフォルトでは以下の状況になるとエラーになります。
+
+- ポインタが指す値が負になる
+- ポインタが負になる
+- ポインタがsizeの範囲を超える
+- clipバッファに負の値が格納される
+
+これを「strictモード」と呼びます。
+
+ただ、Ruby処理系としてみた場合、
+Arrayに格納される値は負でもかまわないし、
+ポインタ（Machine#pointが指す整数）が範囲を超えても問題ありません。
+
+そこで、Ruby処理系として都合が悪い状況になるまでエラーにしないという指定が可能です。
+これを「looseモード」と呼びます
+
+looseモードでは以下の場合でもエラーとみなしません。
+
+- ポインタが範囲を超えたが、値を操作する前に正常範囲に戻った場合
+- ポインタが指す値が負になったが、:out が呼ばれる前に0以上に戻った場合
+- clipバッファに負の値が格納された場合
+
+その場でエラーにしないというだけで、想定した処理がおこなわれるかは状況次第です。
+特に理由がない限り、strictモードで実行してください。
+
+#### flashモード(:flash)
+
+Executor#executeは出力結果の文字列を返しますが、
+本来のBFでは、:out を呼んだ時点で文字を出力します。
+BFと同じく、即時出力をおこなうのが「flashモード」です。
+
+通常の実行時にはさほど差がありませんが、
+debugモードを有効にしていると、出力が混じるのでお勧めできません。
+
+### WindstormのI/Oについて
+
+このドキュメントで使っている「出力先」という言葉は、
+厳密に言うとRuby処理系の_$stdout_が指すIOオブジェクトです。
+通常はRubyを実行しているコンソールになります。
+
+同じく、「入力元」はRuby処理系の_$stdin_が指すIOオブジェクトです。
+通常はRubyを実行しているコンソールからの入力になります。
+
+これらの入出力を変更する必要はありませんが、
+必要であれば、StringIOなどのオブジェクトに差し替えることが可能です。
+Machineに対するspecの記述も参考にしてください。
+
+Note
+---------------
+- windstorm : 暴風 = 上州名物・空っ風
+
+- Windstormを使ってネタプログラム言語を作成するツール、「Youma」もあります
+ - https://github.com/parrot-studio/youma
+ - ネタ言語のサンプルも含まれています
+ - WindstormをWebアプリ等に組み込むのでなければ、Youmaを使ってください
+
+License
+---------------
+The MIT License
+
+see LICENSE file for detail
+
+Author
+---------------
+ぱろっと(@parrot_studio / parrot.studio.dev at gmail.com)

data/Rakefile

@@ -0,0 +1,9 @@
+require "bundler/gem_tasks"
+
+require 'rspec/core'
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec) do |spec|
+  spec.pattern = FileList['spec/**/*_spec.rb']
+end
+
+task :default => :spec

data/lib/windstorm.rb

@@ -0,0 +1,12 @@
+# coding: utf-8
+module Windstorm
+
+  BUFFER_DEFAULT_SIZE = 100
+  COMMANDS = [:pinc, :pdec, :inc, :dec, :out, :inp, :jmp, :ret, :clip, :paste]
+
+end
+
+path = File.join(File.dirname(__FILE__), 'windstorm')
+require File.join(path, 'parser')
+require File.join(path, 'machine')
+require File.join(path, 'executor')

data/lib/windstorm/executor.rb

@@ -0,0 +1,88 @@
+# coding: utf-8
+require 'yaml'
+
+module Windstorm
+  module Reader
+
+    private
+
+    def read(file)
+      raise 'file not found' unless (File.exist?(file) && File.file?(file))
+      File.read(file)
+    end
+
+    def yaml_read(file)
+      YAML.load(read(file))
+    end
+  end
+
+  class Executor
+    include Reader
+
+    attr_writer :parser
+
+    class << self
+      include Reader
+
+      def create_from_file(file)
+        create_from_table(yaml_read(file))
+      end
+
+      def create_from_table(t)
+        create(Parser.create(t))
+      end
+
+      def create(pa)
+        return unless pa
+        ex = self.new
+        ex.parser = pa
+        ex
+      end
+
+    end
+
+    def parser
+      raise 'parser not found' unless @parser
+      @parser
+    end
+
+    def machine
+      raise 'not executed yet' unless @machine
+      @machine
+    end
+
+    def execute(source, params = nil)
+      @machine = Machine.create(parser.build(source), params)
+      @machine.execute
+    end
+
+    def execute_from_file(file, params = nil)
+      execute(read(file), params)
+    end
+
+    def filter(source)
+      parser.filter(source)
+    end
+
+    def filter_from_file(file)
+      filter(read(file))
+    end
+
+    def build(source)
+      parser.build(source)
+    end
+
+    def build_from_file(file)
+      build(read(file))
+    end
+
+    def debug_execute(source, params = nil)
+      execute(source, {:debug => true}.merge(params || {}))
+    end
+
+    def debug_execute_from_file(file, params = nil)
+      debug_execute(read(file), params)
+    end
+
+  end
+end

data/lib/windstorm/machine.rb

@@ -0,0 +1,254 @@
+# coding: utf-8
+module Windstorm
+  class Machine
+
+    attr_writer :commands, :size, :debug, :flash, :loose
+
+    class << self
+
+      def create(coms, params = nil)
+        params ||= {}
+        s = params[:size].to_i
+
+        m = self.new
+        m.commands = coms
+        m.size = s if s > 0
+        m.debug = true if params[:debug]
+        m.flash = true if params[:flash]
+        m.loose = true if params[:loose]
+        m
+      end
+
+      def execute(coms, params = nil)
+        m = create(coms, params)
+        m.execute
+      end
+
+    end
+
+    def execute
+      return result if finish?
+      parse_jump
+      loop do
+        break if finish?
+        step_execute
+      end
+      result
+    end
+
+    def step_execute
+      case com
+      when :pinc
+        move_point_inc
+      when :pdec
+        move_point_dec
+      when :inc
+        increment
+      when :dec
+        decrement
+      when :out
+        output
+      when :inp
+        input
+      when :jmp
+        jump if value == 0
+      when :ret
+        jump unless value == 0
+      when :clip
+        clip
+      when :paste
+        paste
+      end
+      debug_out if debug?
+      forward
+      self
+    end
+
+    def debug?
+      @debug ? true : false
+    end
+
+    def loose?
+      @loose ? true : false
+    end
+
+    def strict?
+      ! loose?
+    end
+
+    def step
+      @step ||= 0
+      @step
+    end
+
+    def add_step
+      @step = step + 1
+      step
+    end
+
+    def commands
+      @commands ||= []
+      @commands
+    end
+
+    def index
+      @index ||= 0
+      @index
+    end
+
+    def add_index
+      @index = index + 1
+      @index
+    end
+
+    def com(ind = nil)
+      ind ||= index
+      commands[ind]
+    end
+
+    def forward
+      add_step
+      add_index
+      self
+    end
+
+    def finish?
+      index >= commands.size ? true : false
+    end
+
+    def jump_table
+      @jump_table ||= {}
+      @jump_table
+    end
+
+    def parse_jump
+      return if commands.empty?
+      inds = []
+      commands.each.with_index do |com, i|
+        case com
+        when :jmp
+          inds << i
+        when :ret
+          hind = inds.delete_at(-1)
+          raise 'jump couples invalid' unless hind
+          jump_table[hind] = i
+          jump_table[i] = hind
+        end
+      end
+      raise 'jump couples invalid' unless inds.empty?
+      if debug? && !jump_table.empty?
+        puts 'jump table:'
+        puts jump_table
+      end
+      self
+    end
+
+    def jump_index(ind)
+      error 'jump index is nil' unless ind
+      strict_error 'out of command index' if ind < 0 || ind >= commands.size
+      @index = ind
+    end
+
+    def jump
+      jump_index(jump_table[index])
+    end
+
+    def size
+      @size ||= BUFFER_DEFAULT_SIZE
+      @size = BUFFER_DEFAULT_SIZE if @size <= 0
+      @size
+    end
+
+    def point
+      @point ||= 0
+      strict_error 'point over' if (@point < 0 || @point >= size)
+      @point
+    end
+
+    def move_point_inc
+      @point = point + 1
+      point
+    end
+
+    def move_point_dec
+      @point = point - 1
+      point
+    end
+
+    def increment
+      replace_value(value+1)
+    end
+
+    def decrement
+      replace_value(value-1)
+    end
+
+    def buffer
+      @buffer ||= []
+      @buffer
+    end
+
+    def value(po = nil)
+      po ||= point
+      strict_error 'point over' if (po < 0 || po >= size)
+      buffer[po] || 0
+    end
+
+    def replace_value(val, po = nil)
+      po ||= point
+      strict_error 'value under 0' if val < 0
+      strict_error 'point over' if (po < 0 || po >= size)
+      buffer[po] = val
+    end
+
+    def cache
+      @cache ||= ""
+      @cache
+    end
+    alias :result :cache
+
+    def output
+      putc value if @flash
+      cache << value.chr
+    end
+
+    def input
+      c = $stdin.getc
+      replace_value(c.bytes.first)
+    end
+
+    def clip_value
+      @clip_value ||= 0
+      @clip_value
+    end
+
+    def replace_clip_value(val)
+      strict_error 'value under 0' if val < 0
+      @clip_value = val
+    end
+
+    def clip
+      replace_clip_value(value)
+    end
+
+    def paste
+      replace_value(clip_value)
+    end
+
+    def debug_out
+      puts "step:#{step} com:#{com} index:#{index} point:#{point} buffer:#{buffer.inspect} clip:#{clip_value} result:#{result}"
+    end
+
+    private
+
+    def error(msg)
+      raise msg
+    end
+
+    def strict_error(msg)
+      return unless strict?
+      error(msg)
+    end
+
+  end
+end