markdown_helper 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 8f73122af24017cc7c6cbd5bb2b7a920d28bc03f
-  data.tar.gz: 73415a069fa49e73e08d95128a885a0adf6a9b65
+  metadata.gz: ace2948d3bb763d09030ba4d4a55fd3f098a6e42
+  data.tar.gz: 8472ec4219bec0e1f81c2c9ced8b1a511efd2858
 SHA512:
-  metadata.gz: 7bb0b0d35c6bb7a0677848d016c53bfcfcba4b8cbb5bf94917de2a8ac2edf1f3e625508c547dac954b605725f8824432e9ad7da9506c03cfd785cda54d0b4929
-  data.tar.gz: 64625aa4899d6db4cffeac7ba22a14b38f557ec3c7e5413ecda9a858c7988c922e44cc2008b8bffe499e3105e3fb67c35b82fc5a79ec58ec573f8e4926338e2a
+  metadata.gz: 1c8641b78321d8d2d8efb659591883efaa80b31510542c28a73778b43a46e78d777176ac66f586d8e001438cc5017635c5172888f529e08224389d091f62a124
+  data.tar.gz: 0b1540cff797e44a371a0c4667bfbcd2ecc75f93fabc068c4738bcd4d4a6a59d50604e3cbe6cb3ceab9039a651c34863299b621f64237969b5afb2ad5c036143

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    markdown_helper (0.1.0)
+    markdown_helper (0.1.1)
 
 GEM
   remote: https://rubygems.org/

data/README.md

@@ -1,6 +1,6 @@
 # MarkdownHelper
 
-## File Inclusion  <img src="/images/include.png" width="50">
+## File Inclusion  <img src="https://github.com/BurdetteLamar/MarkdownHelper/blob/master/images/include.png" width="50">
 
 This markdown helper enables file inclusion in GitHub markdown.
 
@@ -32,9 +32,9 @@ end
 
 or verbatim (which GitHub renders however it likes).
 
-## Usage
+### Usage
 
-### Including Files in Markdown
+#### Specify Include Files with Pragmas
 
 <code>include.md</code>
 ```verbatim
@@ -45,16 +45,19 @@ or verbatim (which GitHub renders however it likes).
 @[:verbatim](include.rb)
 ```
 
-Each inclusion line has:
+An inclusion pragma has the form:
 
-* A leading ```@``` character.
-* A *treatment* in square brackets, one of:
+```@[```*treatment*```](```*relative_file_path*```)```
+
+where:
+
+* *treatment* (in square brackets) is one of the following:
   * Highlighting mode such as ```[ruby]```, to include a highlighted code block.  This can be any Ace mode mentioned in [GitHub Languages](https://github.com/github/linguist/blob/master/lib/linguist/languages.yml).
   * ```[:code_block]```, to include a plain code block.
   * ```[:verbatim]```, to include text verbatim (to be rendered as markdown).
-* A relative file path in parentheses, pointing to the file to be included.
+* *relative_file_path* points to the file to be included.
 
-### Including the Files
+#### Include the Files with ```MarkdownHelper#include```
 
 <code>usage.rb</code>
 ```ruby

data/lib/markdown_helper/version.rb

@@ -1,3 +1,3 @@
 class MarkdownHelper
-  VERSION = '0.1.0'
+  VERSION = '0.1.1'
 end

data/lib/markdown_helper.rb

@@ -1,43 +1,51 @@
 require 'markdown_helper/version'
 
+# Helper class for working with GitHub markdown.
+#  Supports file inclusion.
+#
+# @author Burdette Lamar
 class MarkdownHelper
 
   INCLUDE_REGEXP = /^@\[(:code_block|:verbatim|\w+)\]/
 
-  attr_accessor :tag_as_generated
+  # For later.
+  # attr_accessor :tag_as_generated
 
-    DEFAULT_TREATMENT_FOR_FILE_EXT = {
-      :md => :verbatim,
-      :rb => 'ruby',
-      :xml => 'xml',
-      }
+  # For later.
+  # DEFAULT_TREATMENT_FOR_FILE_EXT = {
+  #     :md => :verbatim,
+  #     :rb => 'ruby',
+  #     :xml => 'xml',
+  # }
 
   def initialize
-    @treatment_for_file_ext = DEFAULT_TREATMENT_FOR_FILE_EXT
-    @treatment_for_file_ext.default = :code_block
-    self.tag_as_generated = false
-  end
-
-  def get_treatment(file_type)
-    @treatment_for_file_ext[file_type]
-  end
-
-  def set_treatment(file_type, treatment)
-    treatment_symbols = [:verbatim, :code_block]
-    if treatment_symbols.include?(treatment) || treatment.kind_of?(String)
-      @treatment_for_file_ext[file_type] = treatment
-    else
-      message = "treatment must be a single word or must be in #{treatment_symbols.inspect}, not #{treatment.inspect}"
-      raise ArgumentError.new(message)
-    end
+    # For later.
+    # @treatment_for_file_ext = DEFAULT_TREATMENT_FOR_FILE_EXT
+    # @treatment_for_file_ext.default = :code_block
+    # self.tag_as_generated = false
   end
 
+  # Merges external files into markdown text.
+  # @param template_file_path [String] the path to the input template markdown file, usually containing include pragmas.
+  # @param markdown_file_path [String] the path to the output merged markdown file.
+  # @raise [RuntimeError] if an include pragma parsing error occurs.
+  # @return [String] the resulting markdown text.
+  #
+  # @example Pragma to include text as a highlighted code block.
+  #   @[ruby](foo.rb)
+  #
+  # @example Pragma to include text as a plain code block.
+  #   @[:code_block](foo.xyz)
+  #
+  # @example Pragma to include text verbatim, to be rendered as markdown.
+  #   @[:verbatim](foo.md)
   def include(template_file_path, markdown_file_path)
     output_lines = []
     File.open(template_file_path, 'r') do |template_file|
-      if tag_as_generated
-        output_lines.push("<!--- GENERATED FILE, DO NOT EDIT --->\n")
-      end
+      # For later.
+      # if tag_as_generated
+      #   output_lines.push("<!--- GENERATED FILE, DO NOT EDIT --->\n")
+      # end
       template_file.each_line do |input_line|
         match_data = input_line.match(INCLUDE_REGEXP)
         unless match_data
@@ -91,4 +99,19 @@ class MarkdownHelper
     output
   end
 
+  # For later.
+  # def get_treatment(file_type)
+  #   @treatment_for_file_ext[file_type]
+  # end
+  #
+  # def set_treatment(file_type, treatment)
+  #   treatment_symbols = [:verbatim, :code_block]
+  #   if treatment_symbols.include?(treatment) || treatment.kind_of?(String)
+  #     @treatment_for_file_ext[file_type] = treatment
+  #   else
+  #     message = "treatment must be a single word or must be in #{treatment_symbols.inspect}, not #{treatment.inspect}"
+  #     raise ArgumentError.new(message)
+  #   end
+  # end
+
 end

data/markdown_helper.gemspec

@@ -9,8 +9,8 @@ Gem::Specification.new do |spec|
   spec.authors       = ['burdettelamar']
   spec.email         = ['BurdetteLamar@Yahoo.com']
 
-  spec.summary       = 'Module to help with GitHub markdown.'
-  spec.description   = 'Module to help with GitHub markdown.  So far:  file inclusion.'
+  spec.summary       = 'Class to help with GitHub markdown.'
+  spec.description   = 'Class to help with GitHub markdown.  So far:  file inclusion.'
   spec.homepage      = 'https://rubygems.org/gems/markdown_helper'
   spec.license       = 'MIT'
 

data/readme/README.template.md

@@ -1,6 +1,6 @@
 # MarkdownHelper
 
-## File Inclusion  <img src="/images/include.png" width="50">
+## File Inclusion  <img src="https://github.com/BurdetteLamar/MarkdownHelper/blob/master/images/include.png" width="50">
 
 This markdown helper enables file inclusion in GitHub markdown.
 
@@ -18,21 +18,24 @@ or plain in a code block:
 
 or verbatim (which GitHub renders however it likes).
 
-## Usage
+### Usage
 
-### Including Files in Markdown
+#### Specify Include Files with Pragmas
 
 @[verbatim](include.md)
 
-Each inclusion line has:
+An inclusion pragma has the form:
 
-* A leading ```@``` character.
-* A *treatment* in square brackets, one of:
+```@[```*treatment*```](```*relative_file_path*```)```
+
+where:
+
+* *treatment* (in square brackets) is one of the following:
   * Highlighting mode such as ```[ruby]```, to include a highlighted code block.  This can be any Ace mode mentioned in [GitHub Languages](https://github.com/github/linguist/blob/master/lib/linguist/languages.yml).
   * ```[:code_block]```, to include a plain code block.
   * ```[:verbatim]```, to include text verbatim (to be rendered as markdown).
-* A relative file path in parentheses, pointing to the file to be included.
+* *relative_file_path* points to the file to be included.
 
-### Including the Files
+#### Include the Files with ```MarkdownHelper#include```
 
 @[ruby](usage.rb)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: markdown_helper
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - burdettelamar
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-02-15 00:00:00.000000000 Z
+date: 2018-02-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -66,7 +66,7 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.3'
-description: 'Module to help with GitHub markdown.  So far:  file inclusion.'
+description: 'Class to help with GitHub markdown.  So far:  file inclusion.'
 email:
 - BurdetteLamar@Yahoo.com
 executables: []
@@ -119,5 +119,5 @@ rubyforge_project:
 rubygems_version: 2.4.5.2
 signing_key: 
 specification_version: 4
-summary: Module to help with GitHub markdown.
+summary: Class to help with GitHub markdown.
 test_files: []