swift-playground 0.0.1

data/lib/swift/playground/debug.rb

@@ -0,0 +1,4 @@
+begin
+  require 'pry'
+rescue LoadError => e
+end

data/lib/swift/playground/generator.rb

@@ -0,0 +1,32 @@
+require_relative 'util'
+
+module Swift
+  class Playground
+    class Generator
+      class << self
+        include Util::PathOrContent
+
+        def generate(markdown, options={})
+          markdown_file = path_or_content_as_io(markdown)
+
+          playground = Playground.new
+
+          pipeline = Util::Pipeline.new(Util::Pipeline::MarkdownFilterChain)
+          converted_markdown = pipeline.call(markdown_file.read)[:output]
+          converted_markdown.xpath('./section').each do |section|
+            case section[:role]
+            when 'documentation'
+              html = section.inner_html
+              playground.sections << DocumentationSection.new(html)
+            when 'code'
+              code = section.xpath('./pre/code').inner_text
+              playground.sections << CodeSection.new(code)
+            end
+          end
+
+          playground
+        end
+      end
+    end
+  end
+end

data/lib/swift/playground/metadata.rb

@@ -0,0 +1,12 @@
+module Swift
+  class Playground
+    NAME = 'swift-playground'
+    SUMMARY = 'Create Xcode Swift Playgrounds, including generating from ' \
+              'Markdown files.'
+    DESCRIPTION = 'A Ruby API and CLI tool for manipulating Xcode Swift '  \
+                  'Playgrounds. Supports generation from markdown files '  \
+                  'with the intent to aide in the production of polished ' \
+                  'playground documents.'
+    VERSION = '0.0.1'
+  end
+end

data/lib/swift/playground/section.rb

@@ -0,0 +1,117 @@
+require 'pathname'
+
+module Swift
+  class Playground
+    sections_path = Pathname.new('swift/playground/sections')
+    autoload :DocumentationSection, sections_path.join('documentation_section')
+    autoload :CodeSection,          sections_path.join('code_section')
+
+    class Section
+      include Util::PathOrContent
+
+      class TemplateContext
+        attr_accessor :content, :number
+
+        extend Forwardable
+        def_delegators :@playground, :stylesheets, :javascripts
+
+        def self.context(*args)
+          new(*args).instance_eval { binding }
+        end
+
+        def context
+          binding
+        end
+
+        def initialize(content, number, playground)
+          @content = content
+          @number = number
+          @playground = playground
+        end
+      end
+
+      attr_reader :content
+
+      class << self
+        protected
+
+        def template
+          unless defined? @template
+            template_root = Pathname.new('../template').expand_path(__FILE__)
+            template_path = template_root.join(@directory, "section.#{@extension}.erb")
+
+            if template_path.exist?
+              template_contents = template_path.read
+            else
+              template_contents = '<%= content %>'
+            end
+            @template = ERB.new(template_contents)
+          end
+
+          @template
+        end
+
+        def extension(extension = nil)
+          @extension = extension unless extension.nil?
+          @extension
+        end
+
+        def directory(path = nil)
+          @directory = Pathname.new(path || '') unless path.nil?
+          @directory
+        end
+
+        def xcplayground(options = nil)
+          @xcplayground_options = options unless options.nil?
+          @xcplayground_options
+        end
+      end
+
+      def initialize(content)
+        @content = path_or_content_as_io(content).read
+        @content.freeze
+      end
+
+      def filename(number)
+        "section-#{number}.#{extension}"
+      end
+
+      def path(number)
+        directory.join filename(number)
+      end
+
+      def xcplayground_node(number)
+        options = xcplayground_options
+
+        node = Nokogiri::XML.fragment("<#{options[:node]}>").children.first
+        node[options[:path_attribute]] = path(number).relative_path_from(directory)
+        node
+      end
+
+      def render(number, playground, custom_content = nil)
+        context = TemplateContext.context custom_content || content,
+                                          number,
+                                          playground
+        template.result(context)
+      end
+
+      protected
+
+      def template
+        self.class.send(:template)
+      end
+
+      def extension
+        self.class.send(:extension)
+      end
+
+      def directory
+        self.class.send(:directory)
+      end
+
+      def xcplayground_options
+        self.class.send(:xcplayground)
+      end
+    end
+  end
+end

data/lib/swift/playground/sections/code_section.rb

@@ -0,0 +1,19 @@
+module Swift
+  class Playground
+    class CodeSection < Section
+      extension 'swift'
+      directory false
+
+      xcplayground node: 'code',
+         path_attribute: 'source-file-name'
+
+      attr_accessor :style
+
+      def xcplayground_node(number)
+        node = super(number)
+        node['style'] = 'setup' if style == 'setup'
+        node
+      end
+    end
+  end
+end

data/lib/swift/playground/sections/documentation_section.rb

@@ -0,0 +1,63 @@
+module Swift
+  class Playground
+    class DocumentationSection < Section
+      extension 'html'
+      directory 'Documentation'
+
+      xcplayground node: 'documentation',
+         path_attribute: 'relative-path'
+
+      attr_reader :assets
+
+      def initialize(content)
+        super(content)
+
+        if @content =~ /(<html|<head|<body)[\s>]/
+          raise 'Please provide an HTML fragment only. ' +
+                'Do not include an <html>, <head> or <body> tag.'
+        end
+
+        extract_assets
+      end
+
+      def render(number, playground)
+        pipeline = Util::Pipeline.new
+        if playground.convert_emoji?
+          pipeline.filters << Util::Pipeline::EmojiFilter
+        end
+
+        if playground.syntax_highlighting
+          if Util::SyntaxHighlighting.available?
+            pipeline.filters << Util::Pipeline::SyntaxHighlightFilter
+          else
+            $stderr.puts "WARNING: Unable to highlight syntax for section " +
+                         "#{number}, please make sure that github-linguist " +
+                         "and pygments.rb gems are installed."
+          end
+        end
+
+        if pipeline.has_filters?
+          processed = pipeline.call(content)
+          super(number, playground, processed[:output].inner_html)
+        else
+          super(number, playground)
+        end
+      end
+
+      private
+
+      def extract_assets
+        @assets = []
+
+        document = Nokogiri::HTML(@content)
+        document.search('//img[@src]').each do |img|
+          image_path = Pathname.new(img['src'])
+
+          if image_path.relative?
+            @assets << Asset.new(img['src'])
+          end
+        end
+      end
+    end
+  end
+end

data/lib/swift/playground/template/Documentation/defaults.css.scss

@@ -0,0 +1,96 @@
+$playground_font_family:      "Helvetica Neue", Helvetica, sans-serif !default;
+$playground_font_size:        1.1rem !default;
+$playground_background_color: #fff !default;
+$playground_text_inset:       6px !default;
+
+$playground_section_separator_height: 1px !default;
+$playground_section_separator_color:  #e7e7e7 !default;
+
+$playground_gutter_width:                   28px !default;
+$playground_gutter_color:                   #fff !default;
+$playground_gutter_right_margin_inset:      8px !default;
+$playground_gutter_right_margin_line_width: 1px !default;
+$playground_gutter_right_margin_line_style: solid !default;
+$playground_gutter_right_margin_line_color: $playground_section_separator_color !default;
+
+// This font adjustment is so that 1rem of Menlo will appear the same size in
+// the HTML sections as it does in the editable swift code sections. For some
+// reason Xcode (6.1.1 - 6A2008a) adds 3 px to the font-size in HTML sections
+// when compared against the font-size used in those code sections. The 'calc'
+// using this adjustment variable compensates for this:
+$playground_font_adjustment:          3px    !default;
+// This separator buffer is needed to avoid the bottom border of a section being
+// reduced by half a pixel sometimes. Instead a transparent 0.5-1px buffer
+// appears below the border which in practice looks better:
+$playground_section_separator_buffer: 1px    !default;
+
+html {
+  // Xcode (6.1.1 - 6A2008a) adds 3px to the font-size in HTML sections when
+  // compared against the font-size used in the swift code sections. The
+  // following 'calc' compensates for this, so 1 rem of Menlo in the HTML will
+  // be the exact same size as code in the swift sections (using the default
+  // Xcode themes that use the Menlo font):
+  font-size: calc(1em - #{$playground_font_adjustment}) ;
+  margin: 0;
+  padding: 0;
+}
+
+body {
+  position: relative;
+  overflow: hidden;
+  margin: 0;
+  box-sizing: border-box;
+
+  font-family: $playground_font_family;
+  font-size: $playground_font_size;
+
+  @if $playground_section_separator_buffer > 0 {
+    border-bottom: $playground_section_separator_buffer solid transparent;
+  }
+
+  background: transparent;
+
+  > section {
+    box-sizing: border-box;
+
+    padding: 0 ($playground_gutter_width + $playground_text_inset);
+    background: $playground_background_color;
+    border: $playground_section_separator_height solid $playground_section_separator_color;
+    border-width: $playground_section_separator_height 0;
+
+    @media (max-height: ($playground_section_separator_height * 2) + 1) {
+      border-bottom: none;
+    }
+  }
+
+  > .gutter {
+    display: block;
+    position: absolute;
+    left: 0;
+    top: $playground_section_separator_height;
+    bottom: $playground_section_separator_height;
+    width: $playground_gutter_width;
+    box-sizing: border-box;
+
+    background: $playground_gutter_color;
+
+    > .margin {
+      display: block;
+      position: absolute;
+      right: 0;
+      top: 0;
+      bottom: 0;
+      width: $playground_gutter_right_margin_inset;
+      box-sizing: border-box;
+
+      border-left: $playground_gutter_right_margin_line_width
+                   $playground_gutter_right_margin_line_style
+                   $playground_gutter_right_margin_line_color;
+    }
+  }
+}
+
+code, pre {
+  font-family: Menlo, "Andale Mono", Monaco, monospace;
+  font-size: 1rem;
+}

data/lib/swift/playground/template/Documentation/section.html.erb

@@ -0,0 +1,23 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8">
+    <title>Section <%= number %></title>
+    <% stylesheets.each_with_index do |stylesheet, index| %>
+      <link rel="stylesheet" type="text/css" href="<%= stylesheet.filename(index + 1) %>">
+    <% end %>
+    <% javascripts.each_with_index do |javascript, index| %>
+      <script src="<%= javascript.filename(index + 1) %>"></script>
+    <% end %>
+    <meta id="xcode-display" name="xcode-display" content="render">
+    <meta name="apple-mobile-web-app-capable" content="yes">
+    <meta name="viewport" content="width=device-width,maximum-scale=1.0">
+  </head>
+
+  <body>
+    <span class="gutter"><span class="margin"></span></span>
+    <section>
+      <%= content %>
+    </section>
+  </body>
+</html>

data/lib/swift/playground/template/contents.xcplayground.erb

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<playground version="3.0" sdk="<%= sdk %>" allows-reset="<%= allows_reset? ? 'YES' : 'NO' %>">
+  <sections>
+  <% sections.each_with_index do |section, index| %>
+    <%= section.xcplayground_node(index + 1).to_xml %>
+  <% end %>
+  </sections>
+</playground>

data/lib/swift/playground/util.rb

@@ -0,0 +1,3 @@
+require_relative 'util/syntax_highlighting'
+require_relative 'util/pipeline'
+require_relative 'util/path_or_content'

data/lib/swift/playground/util/path_or_content.rb

@@ -0,0 +1,31 @@
+require 'pathname'
+
+module Swift::Playground::Util
+  module PathOrContent
+    def path_or_content_as_io(path_or_content)
+      # Return path_or_content if it is an IO-like object
+      return path_or_content if path_or_content.respond_to?(:read)
+
+      unless path_or_content.is_a?(String)
+        raise "You must provide either a String or an IO object when constructing a #{self.class.name}."
+      end
+
+      if path_or_content !~ /[^\n]/ && !path_or_content.blank?
+        path = Pathname.new(path_or_content).expand_path
+        return path if path.exist?
+
+        raise "Path '#{path}' not found. Please add a newline to any raw content."
+      else
+        StringIO.new(path_or_content)
+      end
+    end
+
+    def derived_filename(pathname_or_content)
+      if pathname_or_content.respond_to?(:basename)
+        pathname_or_content.basename.to_s
+      elsif pathname_or_content.respond_to?(:path)
+        File.basename(pathname_or_content.path)
+      end
+    end
+  end
+end

data/lib/swift/playground/util/pipeline.rb

@@ -0,0 +1,53 @@
+require 'html/pipeline'
+require 'active_support/core_ext/object/deep_dup'
+
+require_relative 'syntax_highlighting'
+require_relative 'pipeline/section_filter'
+require_relative 'pipeline/unicode_emoji_filter'
+
+module Swift::Playground::Util
+  class Pipeline
+    HTMLWhitelist = HTML::Pipeline::SanitizationFilter::WHITELIST.deep_dup.tap do |whitelist|
+      # Allow <section> elements to have a 'role' attribute (which we use to
+      # distinguish between sections):
+      whitelist[:elements] << 'section'
+      whitelist[:attributes]['section'] = ['role']
+    end
+
+    MarkdownFilterChain = [
+      HTML::Pipeline::MarkdownFilter,
+
+      # Filter for splitting out resulting HTML into separate HTML and swift
+      # <section> elements, with appropriate metadata attached:
+      SectionFilter,
+
+      HTML::Pipeline::SanitizationFilter
+    ]
+
+    # Custom Emoji filter than replaces with unicode characters rather than
+    # images (because a Swift Playground will always be opened on OS X which
+    # supports rendering the unicode version natively):
+    EmojiFilter = UnicodeEmojiFilter
+
+    SyntaxHighlightFilter = (HTML::Pipeline::SyntaxHighlightFilter if SyntaxHighlighting.available?)
+
+    attr_accessor :filters
+
+    def initialize(filters = [])
+      self.filters = filters
+    end
+
+    def has_filters?
+      self.filters.any?
+    end
+
+    def call(html, context = {}, result = nil)
+      context = {
+        gfm: true, # Enable support for GitHub formatted Markdown
+        whitelist: HTMLWhitelist # Control HTML elements that are sanitized
+      }.merge(context)
+
+      HTML::Pipeline.new(filters.compact, context).call(html, context, result)
+    end
+  end
+end