yome 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: b6627a10cab8313680951f6198cde5e02a80b16d
+  data.tar.gz: '09becf528006b7184739b8debfe83c42f16bf8d6'
+SHA512:
+  metadata.gz: 46a0e32afe42fb922264a53ab8b7be4177baaba18bd7cdff6b736318beeb1120e861822b54b00c565af388c2ecbb4b15f447826f99a089b521c6bf2a02599c93
+  data.tar.gz: 5adf0979c3b171a23bc93fe483b5ec76e6ac98d8b1e0a6cb5254515a23be2dcf2f42858d67f01a57b9e64208b0439055e649ef110f4d262475b37c9d2447c0bd

data/.gitignore

@@ -0,0 +1,9 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+/exe/yome.exe

data/.travis.yml

@@ -0,0 +1,5 @@
+sudo: false
+language: ruby
+rvm:
+  - 2.4.3
+before_install: gem install bundler -v 1.16.1

data/Gemfile

@@ -0,0 +1,6 @@
+source "https://rubygems.org"
+
+git_source(:github) {|repo_name| "https://github.com/#{repo_name}" }
+
+# Specify your gem's dependencies in yome.gemspec
+gemspec

data/Gemfile.lock

@@ -0,0 +1,22 @@
+PATH
+  remote: .
+  specs:
+    yome (0.1.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    minitest (5.11.3)
+    rake (10.5.0)
+
+PLATFORMS
+  x64-mingw32
+
+DEPENDENCIES
+  bundler (~> 1.16)
+  minitest (~> 5.0)
+  rake (~> 10.0)
+  yome!
+
+BUNDLED WITH
+   1.16.1

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2018 ongaeshi
+
+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.ja.md

@@ -0,0 +1,199 @@
+# Yome
+
+注釈付きコメントを使ってコードリーディング文書を生成するツールです。
+
+ソースコード内に`YOME:`という形式のマークアップを埋め込むと、テキストとソースコードを順番に並べたマークダウン文章を作成します。
+
+## インストール
+
+RubyGemsからインストールできます。
+
+    $ gem install yome
+
+Windows向けにバイナリも用意しています。  
+ダウンロードしてパスの通った場所に置いてください。
+
+- [Releases · ongaeshi/yome](https://github.com/ongaeshi/yome/releases/)
+
+## 使い方
+ソースコードを読みながら注釈付きコメントを記述していきます。サンプルでは[1ファイルにのみ](https://github.com/ongaeshi/yome/blob/master/test/data/simple/simple.rb)注釈付きコメントを記述していますが複数ファイルにまたがっても構いません。
+
+```ruby
+# YOME:title Yome simple test
+# YOME:summary This is a simple sample
+# YOME:url https://github.com/ongaeshi/yome/tree/master/test/data/simple
+
+# YOME:4 require
+require "dir"
+
+# YOME:1 Define class
+class Simple
+  # YOME:3 attr_reader
+  attr_reader :x
+
+  # YOME:1.1 Initialize
+  def initialize(x)
+    @x = x
+  end
+
+
+  # YOME:2 Method
+  # YOME: The *to_double* method doubles x and returns it.
+  # YOME: double
+  def to_double
+    2 * x
+  end
+end
+```
+
+コメントを付けたらyomeコマンドを実行します。注釈付きコメントと関連するコードを抜粋して数字の順に並べて表示します。
+
+````bash
+$ cd ~/src
+$ yome
+# Yome simple test
+This is a simple sample
+
+https://github.com/ongaeshi/yome/tree/master/test/data/simple
+
+
+## Define class
+*simple.rb*
+
+
+```ruby
+class Simple
+```
+````
+
+`-o`でファイルに出力します。
+
+```bash
+$ yome -o simple.md
+```
+
+最終出力結果は[simple.md](https://github.com/ongaeshi/yome/blob/master/test/data/simple/simple.md)です。
+
+## リファレンスマニュアル
+### YOME:no (セクション) 
+`YOME:`の後に空白を空けずに数字を記述するとセクションになります。自分よりの下の`YOME: (コメント)`やソースコードを1つにまとめ、数字の順にマークダウンの`##`に変換して出力されます。
+
+数字には小数点も使えます。数値の途中が空いていてもかまいません。
+
+```ruby
+# YOME:1 First section
+class Simple
+  # YOME:10 Second section
+  def foo
+  end
+
+  # YOME:    3 This is not a section
+  def bar
+  end
+end  
+```
+
+### YOME: (コメント)
+`YOME:`の後に空白を空けるとコメントになります。マークダウンの段落になります。
+
+```ruby
+# YOME:1 First section
+# YOME: First section's comment
+class Simple
+  # YOME:10 Second section
+  # YOME: Second section's comment
+  # YOME: Next comment
+  def foo
+  end
+end  
+```
+
+### YOME:title
+`YOME:title`の後に空白を空けるとタイトルになります。マークダウンの`#`に変換して出力されます。記述する場所はファイルの先頭でなくてもかまいません。
+
+```ruby
+# YOME:title Simple class
+
+# YOME:1 First section
+# YOME: First section's comment
+class Simple
+end  
+```
+
+### YOME:summary
+`YOME:summary`の後に空白を空けるとサマリーになります。マークダウンの`#`の後に段落として出力されます。記述する場所はファイルの先頭でなくてもかまいません。
+
+```ruby
+# YOME:title Simple class
+# YOME:summary Behavior of simple class
+
+# YOME:1 First section
+# YOME: First section's comment
+class Simple
+end  
+```
+
+### YOME:url
+`YOME:url`の後に空白を空けるとURLになります。マークダウンの`#`の後にURLを出力します。記述する場所はファイルの先頭でなくてもかまいません。
+
+```ruby
+# YOME:title Simple class
+# YOME:summary Behavior of simple class
+# YOME:url https://github.com/ongaeshi/yome
+
+# YOME:1 First section
+# YOME: First section's comment
+class Simple
+end  
+```
+
+### YOME:end
+セクションのコード抜粋範囲は8行もしくは次のセクションまでです。長いコード範囲を抜粋したいときは`YOME:end`を使ってください。
+
+```ruby
+  # YOME:5 YOME:end
+  # YOME: You can display long distance with `YOME:end`.
+  def long_method
+    1 +
+    2 +
+    3 +
+    4 +
+    5 + 
+    6 +
+    7 +
+    8 +
+    9 +
+    10
+  end
+  # YOME:end
+```
+
+## コマンドラインオプション
+ソースコードの位置、出力ファイル名、未対応のソースコード種類などを指定することができます。
+
+```
+$ yome -h
+Usage: yome [DIR] [options]
+    -o FILE                          Output file name
+        --lang LANG                  Specify code blocks language
+```
+
+## Gitとの連携
+yomeは単体でも使うことができますが、Gitと組み合わせるとさらに便利になります。
+
+```
+# 読みたいソースコードをclone
+$ git clone https://github.com/mruby/mruby.git
+$ cd mruby
+
+# 作業用のブランチを切ると便利
+$ git checkout -b yome/gc
+
+# コメントを書き込んだら定期的にコミットしておきましょう
+$ git commit
+
+# 他のコードエリアを読むときにブランチを切り替えると
+# 別のドキュメントとして生成することができます。
+$ git checkout master
+$ git checkout -b yome/array
+```

data/README.md

@@ -0,0 +1,39 @@
+# Yome
+
+Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/yome`. To experiment with that code, run `bin/console` for an interactive prompt.
+
+TODO: Delete this and the text above, and describe your gem
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'yome'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install yome
+
+## Usage
+
+TODO: Write usage instructions here
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/yome.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,14 @@
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+end
+
+task :default => :test
+
+task :ocra do
+  system "ocra exe/yome --output exe/yome.exe"
+end

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "yome"
+
+# 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.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/exe/yome

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+
+require "yome"
+
+Yome::Cli.exec(ARGV)

data/lib/yome.rb

@@ -0,0 +1,2 @@
+require "yome/cli"
+require "yome/chip"

data/lib/yome/chip.rb

@@ -0,0 +1,54 @@
+module Yome
+  class Chip
+    attr_reader :kind
+    attr_reader :content
+    attr_reader :priority
+    attr_reader :path
+    attr_reader :index
+    attr_reader :end_index
+
+    def initialize(line, path, index)
+      @kind, @content = line.scan(/YOME:([\w.,]*) *(.*)/)[0]
+      @path = path
+      @index = index
+
+      if @kind == ""
+        @kind = "text"
+      else
+        # section?
+        begin 
+          @priority = Float(@kind)
+          @kind = "section"
+        rescue ArgumentError
+        end
+      end
+    end
+
+    def parse(parser)
+      file = parser.file_hash[path]
+
+      i = index + 1
+      while i < file.length do
+        if file[i] =~ /YOME:([\w.,]*) *(.*)/
+          truncate_using_end = true if $1 == "end"
+          break
+        end
+        i += 1
+      end
+
+      @end_index = i - 1
+
+      unless truncate_using_end
+        @end_index = [end_index, index + 8].min
+      end
+
+      while file[end_index] =~ /^\s*$/
+        @end_index -= 1
+      end
+    end
+
+    def has_src?
+      index < end_index
+    end
+  end
+end

data/lib/yome/cli.rb

@@ -0,0 +1,34 @@
+require "find"
+require 'optparse'
+require "yome/lib"
+require "yome/parser"
+require "yome/writer"
+require "yome/version"
+
+module Yome
+  class Cli
+    def self.exec(argv = [])
+      opt = {lang: ""}
+
+      parser = OptionParser.new("Usage: yome [DIR] [options]")
+      parser.on('-o FILE', 'Output file name') {|v| opt[:output] = v }
+      parser.on('--lang LANG', 'Specify code blocks language') {|v| opt[:lang] = v }
+      parser.parse!(argv)
+
+      dir = argv[0] || "."
+      main(dir, opt)
+    end
+
+    def self.main(dir, opt)
+      parser = Parser.new(dir)
+      writer = Writer.new(parser, opt[:lang])
+
+      if opt[:output]
+        File.write(opt[:output], writer.result)
+      else
+        puts writer.result
+      end
+    end
+  end
+end
+  

data/lib/yome/lib.rb

@@ -0,0 +1,12 @@
+module Yome
+  class Lib
+    def self.ignore?(path)
+      path == ".git" || path == "oboe.rb"
+    end
+
+    def self.binary?(path)
+      s = File.read(path, 1024) or return false
+      return s.index("\x00")
+    end 
+  end
+end

data/lib/yome/parser.rb

@@ -0,0 +1,40 @@
+require "yome/lib"
+require "pathname"
+
+module Yome
+  class Parser
+    attr_reader :file_hash, :chips
+
+    def initialize(dir)
+      @file_hash = {}
+      @chips = []
+
+      collect_chips(dir)
+    end
+
+    def collect_chips(dir)
+      Dir.chdir(dir) do
+        Find.find(".") do |path|
+          Find.prune if Lib::ignore?(File.basename(path))
+          next if FileTest.directory?(path) || Lib::binary?(path)
+  
+          begin
+            contents = File.read(path).split("\n")
+          rescue ArgumentError
+            STDERR.puts "Skip: #{path}"
+            next
+          end
+  
+          contents.each_with_index do |line, i|
+            if line =~ /YOME:/
+              path = path.gsub(/^\.\//, "")
+              @file_hash[path] = contents
+              @chips << Chip.new(line, path, i)
+            end
+          end 
+        end
+      end
+    end
+  end
+end
+  

data/lib/yome/section.rb

@@ -0,0 +1,68 @@
+module Yome
+  class Section
+    attr_reader :section
+
+    def initialize(chip)
+      @section = chip
+      @texts = []
+    end
+
+    def priority
+      @section.priority
+    end
+
+    def add_text(chip)
+      @texts << chip
+    end
+
+    def result(parser, lang)
+      <<EOS
+## #{@section.content}
+*#{@section.path}*
+
+#{src_code(parser, @section, false, lang)}
+
+#{@texts.map { |e| src_code(parser, e, true, lang) }.join("\n")}
+EOS
+    end
+
+    private
+
+    def src_code(parser, chip, with_text, lang)
+      lang = detect_lang if lang.empty?
+      r = []
+
+      if with_text
+        r << chip.content
+      end
+      
+      if chip.has_src?
+        r << ""
+        r << "```#{lang}"
+        r << parser.file_hash[chip.path][(chip.index + 1)..(chip.end_index)].join("\n")
+        r << "```"
+      end
+
+      r.join("\n")
+    end
+
+    LANG_HASH = {
+      ".c" => "c",
+      ".cpp" => "cpp",
+      ".cs" => "csharp",
+      ".go" => "golang",
+      ".h" => "cpp",
+      ".hpp" => "cpp",
+      ".js" => "javascript",
+      ".py" => "python",
+      ".rb" => "ruby",
+      ".sh" => "bash",
+    }
+
+    def detect_lang
+      ext = File.extname(@section.path)
+      LANG_HASH[ext]
+    end
+  end
+end
+  

data/lib/yome/version.rb

@@ -0,0 +1,3 @@
+module Yome
+  VERSION = "0.1.0"
+end

data/lib/yome/writer.rb

@@ -0,0 +1,60 @@
+require 'yome/section'
+
+module Yome
+  class Writer
+    def initialize(parser, lang)
+      @title = "NO TITLE"
+      @parser = parser
+      @lang = lang
+      @sections = []
+      @texts = []
+
+      @parser.chips.each do |e|
+        case e.kind
+        when "title"
+          @title = e.content
+        when "summary"
+          @summary = e.content
+        when "url"
+          @url = e.content
+        when "section"
+          @sections << Section.new(e)
+        when "text"
+          @texts << e
+        end
+
+        e.parse(parser)
+      end
+
+      @texts.each do |e|
+        @sections.reverse.each do |sec|
+          if e.path == sec.section.path && e.index > sec.section.index
+            sec.add_text(e)
+            break
+          end
+        end
+      end
+    end
+
+    def header
+      str = ""
+      str += "#{@summary}\n\n" if @summary
+      str += "#{@url}\n\n" if @url
+    end
+
+    def sections
+      @sections.sort_by { |e| e.priority }.map do |e|
+        e.result(@parser, @lang) # TODO: Auto detect lang
+      end.join("\n")
+    end
+
+    def result
+      <<EOS
+\# #{@title}
+#{header}
+#{sections}
+EOS
+    end
+  end
+end
+  

data/yome.gemspec

@@ -0,0 +1,37 @@
+
+lib = File.expand_path("../lib", __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require "yome/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "yome"
+  spec.version       = Yome::VERSION
+  spec.authors       = ["ongaeshi"]
+  spec.email         = ["ongaeshi0621@gmail.com"]
+
+  spec.summary       = %q{Generate the source code reading document from annotated comment.}
+  spec.description   = %q{Generate document when reading source code from annotated comment. It extracts the source code of the place written as YOME: and outputs it in Markdown format.}
+  spec.homepage      = "https://github.com/ongaeshi/yome"
+  spec.license       = "MIT"
+
+  # Prevent pushing this gem to RubyGems.org. To allow pushes either set the 'allowed_push_host'
+  # to allow pushing to a single host or delete this section to allow pushing to any host.
+  if spec.respond_to?(:metadata)
+    spec.metadata["allowed_push_host"] = "https://rubygems.org"
+  else
+    raise "RubyGems 2.0 or newer is required to protect against " \
+      "public gem pushes."
+  end
+
+  spec.files         = `git ls-files -z`.split("\x0").reject do |f|
+    f.match(%r{^(test|spec|features)/})
+  end
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  # spec.add_dependency 'thor'
+  spec.add_development_dependency "bundler", "~> 1.16"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "minitest", "~> 5.0"
+end

metadata

@@ -0,0 +1,110 @@
+--- !ruby/object:Gem::Specification
+name: yome
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- ongaeshi
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2018-08-22 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.16'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.16'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+description: 'Generate document when reading source code from annotated comment. It
+  extracts the source code of the place written as YOME: and outputs it in Markdown
+  format.'
+email:
+- ongaeshi0621@gmail.com
+executables:
+- yome
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".travis.yml"
+- Gemfile
+- Gemfile.lock
+- LICENSE.txt
+- README.ja.md
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- exe/yome
+- lib/yome.rb
+- lib/yome/chip.rb
+- lib/yome/cli.rb
+- lib/yome/lib.rb
+- lib/yome/parser.rb
+- lib/yome/section.rb
+- lib/yome/version.rb
+- lib/yome/writer.rb
+- yome.gemspec
+homepage: https://github.com/ongaeshi/yome
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.6.14
+signing_key: 
+specification_version: 4
+summary: Generate the source code reading document from annotated comment.
+test_files: []