markdown_usage 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 47329a55cb6e0478a1b8cc63b31af8277c0b4044
+  data.tar.gz: 07666dcb0ca5534a2a13ec9141f01d0677c9e1ab
+SHA512:
+  metadata.gz: 72fd086d5627c74a96d3e1a268ee636f9ae59c5870f1832932e2f1805093a3ab2f1f85cff5b172988375921934a442a5dddacf248d5dca9e98311e8976fcadff
+  data.tar.gz: d309be6774f60eb387bf432ce38b1d6c3c7053aa7f5cbfb80a61399b4fc54301aec6f3171441e57823b34aa2662835c75978b1270554c94e7ad1006f0bc87e75

data/.gitignore

@@ -0,0 +1,123 @@
+
+# Created by https://www.gitignore.io/api/emacs,ruby
+
+### Emacs ###
+# -*- mode: gitignore; -*-
+*~
+\#*\#
+/.emacs.desktop
+/.emacs.desktop.lock
+*.elc
+auto-save-list
+tramp
+.\#*
+
+# Org-mode
+.org-id-locations
+*_archive
+
+# flymake-mode
+*_flymake.*
+
+# eshell files
+/eshell/history
+/eshell/lastdir
+
+# elpa packages
+/elpa/
+
+# reftex files
+*.rel
+
+# AUCTeX auto folder
+/auto/
+
+# cask packages
+.cask/
+dist/
+
+# Flycheck
+flycheck_*.el
+
+# server auth directory
+/server/
+
+# projectiles files
+.projectile
+projectile-bookmarks.eld
+
+# directory configuration
+.dir-locals.el
+
+# saveplace
+places
+
+# url cache
+url/cache/
+
+# cedet
+ede-projects.el
+
+# smex
+smex-items
+
+# company-statistics
+company-statistics-cache.el
+
+# anaconda-mode
+anaconda-mode/
+
+### Ruby ###
+*.gem
+*.rbc
+/.config
+/coverage/
+/InstalledFiles
+/pkg/
+/spec/reports/
+/spec/examples.txt
+/test/tmp/
+/test/version_tmp/
+/tmp/
+
+# Used by dotenv library to load environment variables.
+# .env
+
+## Specific to RubyMotion:
+.dat*
+.repl_history
+build/
+*.bridgesupport
+build-iPhoneOS/
+build-iPhoneSimulator/
+
+## Specific to RubyMotion (use of CocoaPods):
+#
+# We recommend against adding the Pods directory to your .gitignore. However
+# you should judge for yourself, the pros and cons are mentioned at:
+# https://guides.cocoapods.org/using/using-cocoapods.html#should-i-check-the-pods-directory-into-source-control
+#
+# vendor/Pods/
+
+## Documentation cache and generated files:
+/.yardoc/
+/_yardoc/
+/doc/
+/rdoc/
+
+## Environment normalization:
+/.bundle/
+/vendor/bundle
+/lib/bundler/man/
+
+# for a library or gem, you might want to ignore these files since the code is
+# intended to run in multiple environments; otherwise, check them in:
+Gemfile.lock
+# .ruby-version
+# .ruby-gemset
+
+# unless supporting rvm < 1.11.0 or doing something fancy, ignore this:
+.rvmrc
+
+
+# End of https://www.gitignore.io/api/emacs,ruby

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.travis.yml

@@ -0,0 +1,7 @@
+language: ruby
+sudo: false
+rvm:
+  - 2.4.0
+before_install: gem install bundler -v 1.16.0
+notifications:
+  email: false

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 markdown-usage.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2018 Skye Shaw
+
+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,214 @@
+# MarkdownUsage
+
+[![Build Status](https://secure.travis-ci.org/sshaw/markdown_usage.svg)](https://secure.travis-ci.org/sshaw/markdown_usage)
+
+Output a colorized version of your program's usage using a Markdown document embedded in your script, from your project's README, or anywhere else.
+
+`MarkdownUsage` uses [`TTY::Markdown`](https://github.com/piotrmurach/tty-markdown) to make
+your program's usage look like this:
+
+![MarkdownUsage output](usage.png)
+
+If your program does not use Ruby or you want to minimize your dependencies use [the `markdown_usage` Script](#markdown_usage-command).
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+**Note: gem is not yet published**
+
+```ruby
+gem "markdown_usage"
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install markdown_usage
+
+## Usage
+
+When it's time to display your program's usage call `MarkdownUsage.print` or `MarkdownUsage()` with the [desired configuration options](#options).
+By default it will look for the usage in [the invoking code's data section](http://ruby-doc.org/docs/keywords/1.9/Object.html#method-i-__END__),
+output it to `stdout`, and call `exit 0`.
+
+For more info see [Options](#options).
+
+### Using `__END__`
+
+Here's an example script:
+
+```rb
+#!/usr/bin/ruby
+
+require "optparse"
+require "markdown_usage"
+
+OptionParser.new do |opts|
+  opts.on "-h", "--help" do
+    MarkdownUsage.print
+  end
+
+  opts.on "-o", "--do-something", "My great option" do |opt|
+    # ...
+  end
+end.parse!
+
+# The rest of your amazing program
+
+__END__
+**my_command** - command to do somethangz
+
+## Usage
+
+`my_command [options] file`
+
+  * `-a`      This does foo
+  * `-b``MAP` Mapping for something
+
+## MAP
+
+Map is a list of blah pairs
+
+## More Info
+
+- [Docs](http://example.com/docs)
+- [Bugs](http://example.com/bugs)
+
+```
+
+
+If you're using this and releasing your script as a gem it must be installed via `gem install --no-wrappers my_gem`
+Otherwise, the data section will not be available to due the wrapper script added by RubyGems.
+
+In this case it's better to use a file for the usage
+
+### Using a File
+
+To extract the program's usage from the `Usage` section of your project's README:
+
+```rb
+MarkdownUsage.print(:source => "README", :sections => "Usage")
+```
+
+This will look for a file name `README.md` or `README.markdown` in your project's root directory.
+
+Multiple sections can be extracted:
+
+```rb
+MarkdownUsage.print(:source => "README", :sections => %w[Usage Support])
+```
+
+To use a different file specify its path:
+
+```rb
+MarkdownUsage.print(:source => "path/to/README.md")
+```
+
+When specifying a path you must provide the appropriate extension.
+
+### Options
+
+`MarkdownUsage.print` and `MarkdownUsage()` accept a `Hash` of the following options:
+
+#### `:exit`
+
+Exit status to use after printing usage, defaults to `0`.
+
+Set this to `false` to prevent `exit` from being called.
+
+#### `:output`
+
+File handle to output the usage on. Defaults to `$stdout`. The given handle must
+have a `#puts` method.
+
+The usage will *always* contain terminal escape codes.
+
+#### `:sections`
+
+Sections to extract from the `:source`. These must be the headings without the
+leading or trailing heading format characters.
+
+If the heading text has other formatting characters, they must be included (see [Examples](#examples)).
+
+Can be a `String` or an `Array` of strings.
+
+#### `:source`
+
+Location of usage Markdown to print, defaults to your program's data (`__END__`) section.
+
+To load a Markdown `README` from your project's root directory set this to `README`.
+
+Relative paths will be loaded relative to your project's root directory.
+
+#### `:raise_errors`
+
+If `true` a `MarkdownUsage::Error` will be raised when `MarkdownUsage` encounters a problem.
+If `false` a warning is sent to `stderr` instead.
+
+## `markdown_usage` Command
+
+Embed or output a colorized version of your program's usage from a Markdown document.
+
+### Usage
+
+```
+markdown_usage [-hv] [-s sections] [-o output] markdown_doc
+```
+
+`markdown_doc` is a file containing the Markdown to use.
+
+- `-h` show this help menu
+- `-o` `output`   where to output the colorized usage, defaults to `stdout`
+- `-s` `sections` sections to extract from `markdown_doc`
+- `-v` show the version
+
+#### `output`
+
+This can be a file or a script. If it's a script it will be added to the script's data section.
+Existing data section content will be overwritten.
+
+We assume `output` is a script if one of the following are true:
+
+- It ends in `.rb` or `.pl` (these languages support data sections)
+- It contains  *nix shebang on the first line for `ruby` or `perl` e.g., `#!/usr/bin/env ruby`
+
+#### `sections`
+
+These must be the headings without leading or trailing heading format characters.
+If the heading text has other formatting characters, they must be included (see [Examples](#examples)).
+
+Multiple sections can be separated by a comma.
+
+### Examples
+
+Output the section `Usage` from `README.md` to `USAGE`:
+
+```
+markdown_usage -s Usage README.md > USAGE
+```
+
+Output the sections `Usage` and `More Info` from `README.md` to `USAGE`:
+
+```
+markdown_usage -s 'Usage,More Info' README.md > USAGE
+```
+
+Add the following formatted section to the data section of `script.rb`:
+
+```
+markdown_usage -s '`markdown_usage` Command' -o script.rb README.md
+```
+
+## See Also
+
+- [`TTY::Markdown`](https://github.com/piotrmurach/tty-markdown) - without this there would be no `MarkdownUsage`
+- [tty_markdown](http://github.com/dapplebeforedawn/tty_markdown)
+- Perl's [`Pod::Usage`](https://metacpan.org/pod/Pod::Usage) - the inspiration for `MarkdownUsage`
+
+## 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,10 @@
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+task :default => :test
+Rake::TestTask.new
+
+desc "Embed the usage doc from README.md in bin/markdown_usage"
+task :embed_usage do
+  sh "bin/markdown_usage -o bin/markdown_usage -s '`markdown_usage` Script' README.md"
+end

data/bin/markdown_usage

@@ -0,0 +1,71 @@
+#!/usr/bin/env ruby
+
+require "stringio"
+require "tempfile"
+require "fileutils"
+
+require "markdown_usage"
+
+def script?(path)
+  # Other langs that support DATA sections?
+  %w[.rb .pl].include?(File.extname(path)) ||
+    File.file?(path) && File.open(path) { |io| return io.gets =~ /\A#!.*\b(?:perl|ruby)/ }
+end
+
+def usage(status = 1)
+  MarkdownUsage(:source => "README", :sections => "`markdown_usage` Command")
+end
+
+options = { :exit => false }
+
+while ARGV.any?
+  case ARGV[0]
+  when "-h", "--help"
+    usage(0)
+  when "-o"
+    ARGV.shift
+    usage unless ARGV[0]
+    output = ARGV.shift
+  when "-s"
+    ARGV.shift
+    usage unless ARGV[0]
+    options[:sections] = ARGV.shift.split(",")
+  when "-v", "--version"
+    puts "v#{MarkdownUsage::VERSION}"
+    exit
+  else
+    options[:source] = ARGV.shift
+  end
+end
+
+usage unless options[:source]
+
+unless output
+  MarkdownUsage(options.merge(:output => $stdout))
+  exit
+end
+
+unless script?(output)
+  File.open(output, "w+") { |io| MarkdownUsage.print(options.merge(:output => io)) }
+  exit
+end
+
+io = StringIO.new
+MarkdownUsage(options.merge(:output => io))
+io.rewind
+
+data = File.read(output)
+code = data.split(/^__END__$/, 2)
+code[1] = io.string
+
+out = Tempfile.new("MarkdownUsage")
+out.puts code[0]
+out.puts "__END__"
+out << code[1]
+out.close
+
+# Will this reset permissions on Windows?
+FileUtils.chmod(File.stat(output).mode, out.path)
+FileUtils.mv(out.path, output)
+
+out.unlink

data/lib/markdown_usage.rb

@@ -0,0 +1,124 @@
+require "tty/markdown"
+require "markdown_usage/version"
+
+module MarkdownUsage
+  Error = Class.new(StandardError)
+
+  HEADING = /\A(\#{1,6})/
+  ALT_HEADING = /\A([-=]+)\s*\Z/
+  ALT_HEADING_LEVELS = { "=" => 1, "-" => 2 }.freeze
+
+  STACKTRACE = /\A(.+):\d+:in\s+`(.+)'/
+
+  EXTENSIONS = %w[md markdown].freeze
+
+  class << self
+    #
+    # Print the calling program's usage based on +options+.
+    # See README for a list of +options+.
+    #
+    def print(options = nil)
+      options ||= {}
+
+      output = options[:output] || $stdout
+      exitcode = options.include?(:exit) ? options[:exit] : 0
+      raise_errors = options.include?(:raise_errors) ? options[:raise_errors] : true
+
+      error("Usage document cannot be found", raise_errors) and return unless defined?(DATA) || options[:source]
+
+      if !options[:source]
+        lines = DATA.readlines
+      else
+
+        source = find_readme(options[:source], find_root_directory)
+        error("Cannot find usage source: #{options[:source]}", raise_errors) and return unless source
+
+        lines = File.readlines(source)
+      end
+
+      output.puts TTY::Markdown.parse(extract_usage(lines, options[:sections]))
+      exit exitcode unless exitcode == false
+    rescue => e
+      error(e, raise_errors)
+    end
+
+    private
+
+    def find_root_directory
+      # caller[0] = MarkdownUsage.print
+      # caller[1] = May be caller or MarkdownUsage(), skip the latter
+      # caller[2] = May be caller
+      root = "."
+      return root unless caller[1] =~ STACKTRACE
+
+      root = File.dirname($1)
+      return root if $2 != "MarkdownUsage"
+
+      root = File.dirname($1) if caller[2] =~ STACKTRACE
+      root
+    end
+
+    def find_readme(source, caller_root)
+      return source if File.exists?(source)
+
+      roots = [ caller_root ]
+      roots << File.dirname(roots[0]) if %w[bin exe].include?(File.basename(roots[0]))
+
+      if source != "README"
+        roots.map { |dir| File.join(dir, source) }.find { |path| File.exists?(path) }
+      else
+        roots.each do |dir|
+          readme = EXTENSIONS.map { |ext| File.join(dir, "README.#{ext}") }.find { |path| File.exists?(path) }
+          return readme if readme
+        end
+
+        nil
+      end
+    end
+
+    def error(message, raise_errors = false)
+      raise Error, message if raise_errors
+      warn "MarkdownUsage warning: #{message}"
+      true
+    end
+
+    def extract_usage(lines, sections)
+      sections = Array(sections).map { |text| Regexp.quote(text) }
+      return lines.join("") unless sections.any?
+
+      usage = ""
+      while lines.any?
+        sections.each do |pat|
+          next unless lines[0] =~ /#{HEADING}\s*#{pat}/ || lines[0] =~ /\A#{pat}/ && lines[1] =~ ALT_HEADING
+
+          # TTY::Markdown (Kramdown) chooses the last char to denote heading level
+          cur_level = lines[0][0] == "#" ? $1.size : ALT_HEADING_LEVELS[$1[-1]]
+
+          usage << lines.shift
+
+          while lines.any?
+            next_level = if lines[0] =~ /#{HEADING}\s*\S/
+                           $1.size
+                         elsif lines[0] =~ /./ && lines[1] =~ ALT_HEADING
+                           ALT_HEADING_LEVELS[$1[-1]]
+                         end
+
+            break if next_level && next_level <= cur_level
+            usage << lines.shift
+          end
+        end
+
+        lines.shift
+      end
+
+      usage
+    end
+  end
+end
+
+#
+# Calls MarkdownUsage.print. See README for +options+.
+#
+def MarkdownUsage(options = nil)
+  MarkdownUsage.print(options)
+end

data/lib/markdown_usage/version.rb

@@ -0,0 +1,3 @@
+module MarkdownUsage
+  VERSION = "0.0.1"
+end

data/markdown_usage.gemspec

@@ -0,0 +1,30 @@
+lib = File.expand_path("../lib", __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require "markdown_usage/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "markdown_usage"
+  spec.version       = MarkdownUsage::VERSION
+  spec.authors       = ["Skye Shaw"]
+  spec.email         = ["skye.shaw@gmail.com"]
+  spec.summary =<<-DESC
+    Output a colorized version of your program's usage using a Markdown document embedded in your script,
+    from your project's README, or anywhere else.
+  DESC
+  spec.homepage      = "https://github.com/sshaw/markdown_usage"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0").reject do |f|
+    f.match(%r{^(test|spec|features)/})
+  end
+  spec.bindir        = "bin"
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "tty-markdown", "~> 0.2"
+  spec.add_development_dependency "bundler", "~> 1.12"
+  spec.add_development_dependency "climate_control", "~> 0.1"
+  spec.add_development_dependency "io-grab", "~> 0.0.2"
+  spec.add_development_dependency "minitest", "~> 5.0"
+  spec.add_development_dependency "rake", "~> 10.0"
+end

metadata

@@ -0,0 +1,142 @@
+--- !ruby/object:Gem::Specification
+name: markdown_usage
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Skye Shaw
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2018-01-30 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: tty-markdown
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.12'
+- !ruby/object:Gem::Dependency
+  name: climate_control
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+- !ruby/object:Gem::Dependency
+  name: io-grab
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.0.2
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.0.2
+- !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'
+- !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'
+description: 
+email:
+- skye.shaw@gmail.com
+executables:
+- markdown_usage
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- ".travis.yml"
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/markdown_usage
+- lib/markdown_usage.rb
+- lib/markdown_usage/version.rb
+- markdown_usage.gemspec
+- usage.png
+homepage: https://github.com/sshaw/markdown_usage
+licenses:
+- MIT
+metadata: {}
+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: Output a colorized version of your program's usage using a Markdown document
+  embedded in your script, from your project's README, or anywhere else.
+test_files: []