playgroundbook 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: b9284005e400363b56c6ad72c74da1d147b5f63b
-  data.tar.gz: e082821228fd38d19d3af795a62d5c80988ecc86
+  metadata.gz: 0cb1f23c12d4c4d5da05b5bd17d0c9309a7d9b68
+  data.tar.gz: 06141cc3c18eb69eb0885438b2e60ab71cc75f67
 SHA512:
-  metadata.gz: 351ca7d6d4c5af5c6246ccfeb76c7139adde5eeec7a5bcc666b8ed1d1ecf7afc1de90a05ccfca3eacc9d9297af53e7c26947acf9b4a0abfc4f6c0738e7b99b1e
-  data.tar.gz: 380e9c62a03fab27bfff3e64b8f9262f9ebc895b992306eaa49a85428197ec8989b54180aa85013e7ef8e87f901394ee816e3c4c8ee653cda3d3ab61903740ad
+  metadata.gz: db1e4fe2b6a940c9bce9b1ebe085fb347bb2fd43efb8e422ed14a2c8e185da3e527d60e2d5ec8859e769f2cc7ba3b421d2f7520b45501e6eedee71e24f983922
+  data.tar.gz: f0852a23faa7728b67a1cd4cca7eda21e7174ba487cfb8b4f3dbaf889213e6405b1229ec27e7ea5523af3074fb0e8a9ab7c3174b07fc81856f12b814ed014135

data/Changelog.md

@@ -2,6 +2,11 @@
 
 - Nothing yet.
 
+# 0.3.0
+
+- Glossary support. See [#18](https://github.com/ashfurrow/playgroundbook/issues/18).
+- Removes newlines surrounding markdown blocks. See [#20](https://github.com/ashfurrow/playgroundbook/issues/20).
+
 # 0.2.1
 
 - Support for cover images. See [#16](https://github.com/ashfurrow/playgroundbook/issues/16).

data/README.md

@@ -39,9 +39,17 @@ chapters:
   - Chapter 1
   - Chapter 2
   - etc...
+glossary:
+  term: definition
 ```
 
-Each chapter needs to have a corresponding playground; so `Chapter 1` requires there be a `Chapter 1.playground` playground. The playgrounds can reference (not copy) resources from an optionally specified directory. `import` frameworks are specified in the yaml file and are added to every page of the book. You can specify a cover image file name that's stored in the `resources` directory (it should be 400x300 pixels). 
+Each chapter needs to have a corresponding playground; so `Chapter 1` requires there be a `Chapter 1.playground` playground. The playgrounds can reference (not copy) resources from an optionally specified directory. `import` frameworks are specified in the yaml file and are added to every page of the book. You can specify a cover image file name that's stored in the `resources` directory (it should be 400x300 pixels). Finally, you can supply a glossary, a dictionary of term/definition pairs. This lets you link to terms in markdown. For example:
+
+```md
+... [term](glossary://term) ...
+```
+
+Only the link to the term must be URL encoded. For example, the term "reuse identifier" would be defined in the yaml as `reuse identifier` but linked to as `glossary://reuse%20identifier`.  
 
 Each chapter needs to be in the following format:
 

data/lib/playgroundbook_renderer/chapter_collator.rb

@@ -11,47 +11,29 @@ module Playgroundbook
       @ui = ui
     end
 
-    def collate!(chapter_name, chapter_file_contents, imports)
+    def collate!(chapter_name, parsed_chapter, imports)
       @ui.puts "Processing #{chapter_name.green}."
 
       chapter_directory_name = "#{chapter_name}.playgroundchapter"
       Dir.mkdir(chapter_directory_name) unless Dir.exist?(chapter_directory_name)
-      Dir.chdir(chapter_directory_name) do
-        pages = parse_pages(chapter_file_contents)
-        
+      Dir.chdir(chapter_directory_name) do        
         Dir.mkdir(PagesDirectoryName) unless Dir.exist?(PagesDirectoryName)
         Dir.chdir(PagesDirectoryName) do
-          pages[:page_names].each_with_index do |page_name, index|
+          parsed_chapter[:page_names].each_with_index do |page_name, index|
             @ui.puts "  Processing #{page_name.green}."
 
-            page_contents = pages[:page_contents][index]
-            page_dir_name = pages[:page_dir_names][index]
+            page_contents = parsed_chapter[:page_contents][index]
+            page_dir_name = parsed_chapter[:page_dir_names][index]
 
             @page_writer.write_page!(page_name, page_dir_name, imports, page_contents)
           end
         end
 
-        write_chapter_manifest!(chapter_name, pages[:page_dir_names])
-        write_preamble!(pages[:preamble])
+        write_chapter_manifest!(chapter_name, parsed_chapter[:page_dir_names])
+        write_preamble!(parsed_chapter[:preamble])
       end
     end
 
-    def parse_pages(swift)
-      page_names = swift.scan(/\/\/\/\/.*$/).map { |p| p.gsub('////', '').strip }
-      page_dir_names = page_names.map { |p| "#{p}.playgroundpage" }
-
-      split_file = swift.split(/\/\/\/\/.*$/)
-      page_contents = split_file.drop(1).map { |p| p.strip }
-      preamble = split_file.first.strip
-
-      {
-        page_dir_names: page_dir_names,
-        page_names: page_names,
-        page_contents: page_contents,
-        preamble: preamble,
-      }
-    end
-
     def write_chapter_manifest!(chapter_name, page_dir_names)
       manifest_contents = {
         'Name' => chapter_name,

data/lib/playgroundbook_renderer/glossary_generator.rb

@@ -0,0 +1,47 @@
+require 'uri'
+
+module Playgroundbook
+  GlossaryFileName = 'Glossary.plist'.freeze
+
+  class GlossaryGenerator
+    def generate!(parsed_chapters, chapter_names, glossary)
+      glossary_plist = {
+        'Terms' => {}
+      }
+
+      glossary.each do |term, definition|
+        glossary_plist['Terms'][term] = { 'Definition' => definition }
+        escaped_term = URI.escape(term)
+        parsed_chapters.each_with_index do |chapter, i|
+          pages = chapter[:page_contents]
+          page_names = chapter[:page_names]
+          chapter_name = URI.escape(chapter_names[i])
+
+          pages.each_with_index do |page, j|
+            page_name = URI.escape(page_names[j])
+            unless page.scan("](glossary://#{escaped_term})").empty?
+              glossary_plist['Terms'][term].merge!({
+                'FirstUse' => {
+                  'Title' => page_names[j],
+                  'PageReference' => "#{chapter_name}/#{page_name}",
+                }
+              })
+              break
+            end
+          end
+
+          # Break if we found the first user.
+          break unless glossary_plist['Terms'][term]['FirstUse'].empty?
+        end
+      end
+
+      File.open(glossary_file_name, 'w') do |file|
+        file.write(glossary_plist.to_plist)
+      end
+    end
+
+    def glossary_file_name
+      "#{ContentsDirectoryName}/#{ResourcesDirectoryName}/#{GlossaryFileName}"
+    end
+  end
+end

data/lib/playgroundbook_renderer/page_parser.rb

@@ -0,0 +1,19 @@
+module Playgroundbook
+  class PageParser
+    def parse_chapter_pages(chapter_contents)
+      page_names = chapter_contents.scan(/\/\/\/\/.*$/).map { |p| p.gsub('////', '').strip }
+      page_dir_names = page_names.map { |p| "#{p}.playgroundpage" }
+
+      split_file = chapter_contents.split(/\/\/\/\/.*$/)
+      page_contents = split_file.drop(1).map { |p| p.strip }
+      preamble = split_file.first.strip
+
+      {
+        page_dir_names: page_dir_names,
+        page_names: page_names,
+        page_contents: page_contents,
+        preamble: preamble,
+      }
+    end
+  end
+end

data/lib/playgroundbook_renderer/page_processor.rb

@@ -0,0 +1,15 @@
+module Playgroundbook
+  class PageProcessor
+    def strip_extraneous_newlines(page_contents)
+      # Three cases we need to look for:
+      # - Extraneous newlines before /*:
+      # - Extraneous newlines after */
+      # - Extraneous newlines either before or after //:
+      page_contents
+        .gsub(/\n+\/\*:/, "\n/*:")
+        .gsub(/\*\/\n+/, "*/\n")
+        .split(/(\/\/:.*$)\n*/).join("\n") # Important to do this before the next line, because it adds newlines before //: comments.
+        .gsub(/\n+\/\/:/, "\n//:")
+    end
+  end
+end

data/lib/playgroundbook_renderer/page_writer.rb

@@ -1,9 +1,10 @@
 require 'plist'
+require 'playgroundbook_renderer/page_processor'
 
 module Playgroundbook
   class PageWriter
-
-    def initialize(ui = Cork::Board.new)
+    def initialize(page_processor = PageProcessor.new, ui = Cork::Board.new)
+      @page_processor = page_processor
       @ui = ui
     end
 
@@ -13,7 +14,7 @@ module Playgroundbook
       contents_with_import = "//#-hidden-code\n"
       contents_with_import += imports.map { |i| "import #{i}" }.join("\n") + "\n"
       contents_with_import += "//#-end-hidden-code\n"
-      contents_with_import += page_contents
+      contents_with_import += @page_processor.strip_extraneous_newlines(page_contents)
 
       Dir.chdir(page_dir_name) do
         File.open(ContentsSwiftFileName, 'w') do |file|

data/lib/playgroundbook_renderer/playgroundbook_renderer.rb

@@ -4,25 +4,33 @@ require 'yaml'
 require 'fileutils'
 require 'playgroundbook_renderer/contents_manifest_generator'
 require 'playgroundbook_renderer/chapter_collator'
+require 'playgroundbook_renderer/page_parser'
+require 'playgroundbook_renderer/glossary_generator'
 
 module Playgroundbook
-  ContentsDirName = 'Contents'
+  ContentsDirectoryName = 'Contents'
   ChaptersDirName = 'Chapters'
 
   # A renderer for playground books.
   class Renderer < AbstractLinter
     attr_accessor :yaml_file_name
     attr_accessor :contents_manifest_generator
+    attr_accessor :page_parser
     attr_accessor :chapter_collator
+    attr_accessor :glossary_generator
     attr_accessor :ui
 
     def initialize(yaml_file_name, 
-        contents_manifest_generator = ContentsManifestGenerator.new, 
+        contents_manifest_generator = ContentsManifestGenerator.new,
+        page_parser = PageParser.new,
         chapter_collator = ChapterCollator.new,
+        glossary_generator = GlossaryGenerator.new,
         ui = Cork::Board.new)
       @yaml_file_name = yaml_file_name
       @contents_manifest_generator = contents_manifest_generator
+      @page_parser = page_parser
       @chapter_collator = chapter_collator
+      @glossary_generator = glossary_generator
       @ui = ui
     end
 
@@ -41,15 +49,16 @@ module Playgroundbook
         ui.puts 'Failed to open playground Contents.swift file.'
         raise e
       end
+      parsed_chapters = book_chapter_contents.map { |c| page_parser.parse_chapter_pages(c) }
 
       Dir.mkdir(book_dir_name) unless Dir.exist?(book_dir_name)
       Dir.chdir(book_dir_name) do
-        Dir.mkdir(ContentsDirName) unless Dir.exist?(ContentsDirName)
-        Dir.chdir(ContentsDirName) do
+        Dir.mkdir(ContentsDirectoryName) unless Dir.exist?(ContentsDirectoryName)
+        Dir.chdir(ContentsDirectoryName) do
+          Dir.mkdir(ResourcesDirectoryName) unless Dir.exist?(ResourcesDirectoryName) # Always create a Resources dir, even if empty.
           resources_dir = book['resources']
           if !(resources_dir.nil? || resources_dir.empty?)
             @ui.puts "Copying resource directory (#{resources_dir.green}) contents."
-            Dir.mkdir(ResourcesDirectoryName) unless Dir.exist?(ResourcesDirectoryName)
             Dir.glob("../../#{resources_dir}/*").each do |file|
               FileUtils.cp(file, ResourcesDirectoryName)
             end
@@ -60,11 +69,16 @@ module Playgroundbook
           Dir.chdir(ChaptersDirName) do
             # Chapter file name becomes chapter name in playground book.
             book['chapters'].each_with_index do |chapter_file_name, index|
-              chapter_file_contents = book_chapter_contents[index]
-              @chapter_collator.collate!(chapter_file_name, chapter_file_contents, book['imports'] || ['UIKit'])
+              parsed_chapter = parsed_chapters[index]
+              @chapter_collator.collate!(chapter_file_name, parsed_chapter, book['imports'] || ['UIKit'])
             end
           end
         end
+
+        unless book['glossary'].nil?
+          @ui.puts 'Generating glossary.'
+          @glossary_generator.generate!(parsed_chapters, book['chapters'], book['glossary'])
+        end 
       end
     end
 

data/lib/version.rb

@@ -1,3 +1,3 @@
 module Playgroundbook
-  VERSION = '0.2.1'.freeze
+  VERSION = '0.3.0'.freeze
 end

data/spec/playgroundbook_renderer_spec/chapter_collator_spec.rb

@@ -6,7 +6,7 @@ module Playgroundbook
     let(:collator) { ChapterCollator.new(page_writer, test_ui) }
     let(:page_writer) { double(PageWriter) }
     let(:test_ui) { Cork::Board.new(silent: true) }
-    let(:chapter_contents) { test_chapter_contents }
+    let(:parsed_chapter) { PageParser.new.parse_chapter_pages(test_chapter_contents) }
     let(:chapter_name) { 'test_chapter' }
 
     before do
@@ -14,14 +14,14 @@ module Playgroundbook
     end
 
     it 'creates a chapter manifest' do
-      collator.collate!(chapter_name, chapter_contents, [])
+      collator.collate!(chapter_name, parsed_chapter, [])
 
       expect(File.exist?("#{chapter_name}.playgroundchapter/#{ManifestFileName}")).to be_truthy
     end
 
     context 'the chapter manifest' do
       before do
-        collator.collate!(chapter_name, chapter_contents, ['UIKit'])
+        collator.collate!(chapter_name, parsed_chapter, ['UIKit'])
       end
 
       it 'has the correct name' do
@@ -40,16 +40,16 @@ module Playgroundbook
       expect(page_writer).to receive(:write_page!).with("Page 1", "Page 1.playgroundpage", [], "str = \"Yo, it's page 1.\"\nsharedFunc()")
       expect(page_writer).to receive(:write_page!).with("Page 2", "Page 2.playgroundpage", [], "str = \"Page 2 awww yeah.\"\nsharedFunc()")
 
-      collator.collate!(chapter_name, chapter_contents, [])
+      collator.collate!(chapter_name, parsed_chapter, [])
     end
 
     it 'does not explode if a Source directory already exists' do
-      expect{ collator.collate!(chapter_name, chapter_contents, []) }.to_not raise_error
+      expect{ collator.collate!(chapter_name, parsed_chapter, []) }.to_not raise_error
     end
     
     context 'having colated' do
       before do
-        collator.collate!(chapter_name, chapter_contents, [])
+        collator.collate!(chapter_name, parsed_chapter, [])
       end
 
       it 'creates a Source directory if one does not exist' do

data/spec/playgroundbook_renderer_spec/glossary_generator_spec.rb

@@ -0,0 +1,52 @@
+require File.expand_path('../../spec_helper', __FILE__)
+
+module Playgroundbook
+  describe GlossaryGenerator do
+    include FakeFS::SpecHelpers
+    let(:glossary_generator) { GlossaryGenerator.new }
+    let(:glossary) {{
+      'example term' => 'example definition'
+    }}
+    let(:glossary_file_name) { 'Contents/Resources/Glossary.plist' }
+
+    before do
+      FileUtils.mkdir_p('Contents/Resources')
+    end
+
+    it 'generates a glossary plist' do
+      glossary_generator.generate!({}, [], glossary)
+      
+      expect(File.exist?(glossary_file_name)).to be_truthy
+    end
+
+    context 'glossary plist' do
+      let(:glossary_plist) { Plist.parse_xml(glossary_file_name) }
+
+      it 'has a glossary with correct terms' do
+        glossary_generator.generate!({}, [], glossary)
+
+        expect(glossary_plist['Terms']['example term']['Definition']).to eq('example definition')
+      end
+
+      it 'generates correct first use page references' do
+        glossary_generator.generate!([
+            {
+              page_names: ['Page 1'],
+              page_contents: ["/*: Here's how to use [a thing](glossary://example%20term) */"],
+            },
+            {
+              page_names: ['Should not see this'],
+              page_contents: ["/*: Here's how to use [a thing](glossary://example%20term) even though this shouldn't match' */"],
+            }
+          ],
+          ['Chapter 1', 'Chapter 2'], 
+          glossary)
+        
+        expect(glossary_plist['Terms']['example term']['FirstUse']).to eq({
+          'PageReference' => 'Chapter%201/Page%201',
+          'Title' => 'Page 1'
+        })
+      end
+    end
+  end
+end

data/spec/playgroundbook_renderer_spec/page_processor_spec.rb

@@ -0,0 +1,86 @@
+require File.expand_path('../../spec_helper', __FILE__)
+
+module Playgroundbook
+  describe PageProcessor do
+    let(:page_processor) { PageProcessor.new }
+    
+    it 'removes newlines before markdown blocks' do
+      page_contents = <<-EOS
+let a = 6
+
+/*:
+ Some markdown.
+*/
+      EOS
+      processed_page_contents = <<-EOS
+let a = 6
+/*:
+ Some markdown.
+*/
+      EOS
+      
+      expect(page_processor.strip_extraneous_newlines(page_contents)).to eq(processed_page_contents)
+    end
+
+    it 'removes newlines after markdown blocks' do
+      page_contents = <<-EOS
+/*:
+ Some markdown.
+*/
+
+let a = 6
+      EOS
+      processed_page_contents = <<-EOS
+/*:
+ Some markdown.
+*/
+let a = 6
+      EOS
+      
+      expect(page_processor.strip_extraneous_newlines(page_contents)).to eq(processed_page_contents)
+    end
+
+    it 'removes newlines surrounding single-line markdown blocks' do
+      page_contents = <<-EOS
+let a = 6
+
+//: Some markdown.
+
+let b = a
+      EOS
+      processed_page_contents = <<-EOS
+let a = 6
+//: Some markdown.
+let b = a
+      EOS
+      
+      expect(page_processor.strip_extraneous_newlines(page_contents)).to eq(processed_page_contents)
+    end
+
+    it 'does not strip newlines from code' do
+      page_contents = <<-EOS
+let a = 6
+
+let b = a
+      EOS
+
+      expect(page_processor.strip_extraneous_newlines(page_contents)).to eq(page_contents)
+    end
+
+    it 'it does not strip newlines from the markdown' do
+      page_contents = <<-EOS
+/*:
+
+ # Header
+ 
+ Some markdown. The following lines are purposefull left blank.
+
+
+
+*/
+      EOS
+      
+      expect(page_processor.strip_extraneous_newlines(page_contents)).to eq(page_contents)
+    end
+  end
+end

data/spec/playgroundbook_renderer_spec/page_writer_spec.rb

@@ -3,13 +3,21 @@ require File.expand_path('../../spec_helper', __FILE__)
 module Playgroundbook
   describe PageWriter do
     include FakeFS::SpecHelpers
-    let(:page_writer) { PageWriter.new(test_ui) }
+    let(:page_writer) { PageWriter.new(page_processor, test_ui) }
+    let(:page_processor) { double(PageProcessor) }
     let(:test_ui) { Cork::Board.new(silent: true) }
     let(:page_name) { 'test page name' }
     let(:page_dir_name) { 'test page name.playgroundpage' }
     let(:page_contents) { "// Some swift goes here." }
     let(:generated_page_contesnts) { "//#-hidden-code\nimport UIKit\n//#-end-hidden-code\n// Some swift goes here." }
 
+    before do
+      allow(page_processor).to receive(:strip_extraneous_newlines) do |page_contents|
+        # Returns the parameter, unprocessed.
+        page_contents
+      end
+    end
+
     context 'with a pre-existing page directory' do
       before do
         Dir.mkdir(page_dir_name)
@@ -20,6 +28,11 @@ module Playgroundbook
       end
     end
 
+    it 'calls the page processor' do
+      expect(page_processor).to receive(:strip_extraneous_newlines)
+      page_writer.write_page!(page_name, page_dir_name, ['UIKit'],  page_contents)
+    end
+
     context 'as a consequence of writing rendering' do
       before do
         page_writer.write_page!(page_name, page_dir_name, ['UIKit'],  page_contents)

data/spec/playgroundbook_renderer_spec/playgroundbook_renderer_spec.rb

@@ -3,10 +3,12 @@ require File.expand_path('../../spec_helper', __FILE__)
 module Playgroundbook
   describe Renderer do
     include FakeFS::SpecHelpers
-    let(:renderer) { Renderer.new(yaml_file_name, contents_manifest_generator, chapter_collator, test_ui) }
+    let(:renderer) { Renderer.new(yaml_file_name, contents_manifest_generator, page_parser, chapter_collator, glossary_generator, test_ui) }
     let(:yaml_file_name) { 'book.yml' }
     let(:contents_manifest_generator) { double(ContentsManifestGenerator) }
+    let(:page_parser) { double(PageParser) }
     let(:chapter_collator) { double(ChapterCollator) }
+    let(:glossary_generator) { double(GlossaryGenerator) }
     let(:test_ui) { Cork::Board.new(silent: true) }
 
     before do
@@ -16,6 +18,7 @@ module Playgroundbook
 
       allow(contents_manifest_generator).to receive(:generate!)
       allow(chapter_collator).to receive(:collate!)
+      allow(glossary_generator).to receive(:generate!)
     end
 
     it 'initializes correctly' do
@@ -28,6 +31,7 @@ module Playgroundbook
 
     context 'with a playground' do
       before do
+        allow(page_parser).to receive(:parse_chapter_pages)
         Dir.mkdir('assets')
         FileUtils.touch('assets/file.png')
         Dir.mkdir('test_chapter.playground/')
@@ -107,6 +111,12 @@ module Playgroundbook
           end
         end
       end
+
+      it 'generates a glossary' do
+        expect(glossary_generator).to receive(:generate!)
+
+        renderer.render!
+      end
     end
   end
 end

data/spec/spec_helper.rb

@@ -24,6 +24,9 @@ require 'playgroundbook_lint/root_manifest_linter'
 require 'playgroundbook_renderer/contents_manifest_generator'
 require 'playgroundbook_renderer/chapter_collator'
 require 'playgroundbook_renderer/page_writer'
+require 'playgroundbook_renderer/page_parser'
+require 'playgroundbook_renderer/glossary_generator'
+require 'playgroundbook_renderer/page_processor'
 
 RSpec.configure do |config|
   config.color = true
@@ -46,6 +49,11 @@ def test_book_metadata
     'identifier' => 'com.ashfurrow.testing',
     'resources' => 'assets',
     'cover' => 'file.jpeg',
+    'glossary' => [
+      {
+        'term' => 'definition'
+      }
+    ]
   }
 end
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: playgroundbook
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.3.0
 platform: ruby
 authors:
 - Ash Furrow
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-08-29 00:00:00.000000000 Z
+date: 2016-09-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: plist
@@ -85,6 +85,9 @@ files:
 - lib/playgroundbook_lint/root_manifest_linter.rb
 - lib/playgroundbook_renderer/chapter_collator.rb
 - lib/playgroundbook_renderer/contents_manifest_generator.rb
+- lib/playgroundbook_renderer/glossary_generator.rb
+- lib/playgroundbook_renderer/page_parser.rb
+- lib/playgroundbook_renderer/page_processor.rb
 - lib/playgroundbook_renderer/page_writer.rb
 - lib/playgroundbook_renderer/playgroundbook_renderer.rb
 - lib/version.rb
@@ -111,6 +114,8 @@ files:
 - spec/playground_book_lint/root_manifest_linter_spec.rb
 - spec/playgroundbook_renderer_spec/chapter_collator_spec.rb
 - spec/playgroundbook_renderer_spec/contents_manfiest_generator_spec.rb
+- spec/playgroundbook_renderer_spec/glossary_generator_spec.rb
+- spec/playgroundbook_renderer_spec/page_processor_spec.rb
 - spec/playgroundbook_renderer_spec/page_writer_spec.rb
 - spec/playgroundbook_renderer_spec/playgroundbook_renderer_spec.rb
 - spec/spec_helper.rb