Section <%= number %>

elements, with appropriate metadata attached: 22 | SectionFilter, 23 | 24 | HTML::Pipeline::SanitizationFilter 25 | ] 26 | 27 | # Custom Emoji filter than replaces with unicode characters rather than 28 | # images (because a Swift Playground will always be opened on OS X which 29 | # supports rendering the unicode version natively): 30 | EmojiFilter = UnicodeEmojiFilter 31 | 32 | SyntaxHighlightFilter = (HTML::Pipeline::SyntaxHighlightFilter if SyntaxHighlighting.available?) 33 | 34 | attr_accessor :filters 35 | 36 | def initialize(filters = []) 37 | self.filters = filters 38 | end 39 | 40 | def has_filters? 41 | self.filters.any? 42 | end 43 | 44 | def call(html, context = {}, result = nil) 45 | context = { 46 | gfm: true, # Enable support for GitHub formatted Markdown 47 | whitelist: HTMLWhitelist # Control HTML elements that are sanitized 48 | }.merge(context) 49 | 50 | HTML::Pipeline.new(filters.compact, context).call(html, context, result) 51 | end 52 | end 53 | end 54 | -------------------------------------------------------------------------------- /lib/swift/playground/sections/documentation_section.rb: -------------------------------------------------------------------------------- 1 | module Swift 2 | class Playground 3 | class DocumentationSection < Section 4 | extension 'html' 5 | directory 'Documentation' 6 | 7 | xcplayground node: 'documentation', 8 | path_attribute: 'relative-path' 9 | 10 | attr_reader :assets 11 | 12 | def initialize(content) 13 | super(content) 14 | 15 | if @content =~ /(]/ 16 | raise 'Please provide an HTML fragment only. ' + 17 | 'Do not include an , or tag.' 18 | end 19 | 20 | extract_assets 21 | end 22 | 23 | def render(number, playground) 24 | pipeline = Util::Pipeline.new 25 | if playground.convert_emoji? 26 | pipeline.filters << Util::Pipeline::EmojiFilter 27 | end 28 | 29 | if playground.syntax_highlighting 30 | if Util::SyntaxHighlighting.available? 31 | pipeline.filters << Util::Pipeline::SyntaxHighlightFilter 32 | else 33 | $stderr.puts "WARNING: Unable to highlight syntax for section " + 34 | "#{number}, please make sure that github-linguist " + 35 | "and pygments.rb gems are installed." 36 | end 37 | end 38 | 39 | if pipeline.has_filters? 40 | processed = pipeline.call(content) 41 | super(number, playground, processed[:output].inner_html) 42 | else 43 | super(number, playground) 44 | end 45 | end 46 | 47 | private 48 | 49 | def extract_assets 50 | @assets = [] 51 | 52 | document = Nokogiri::HTML(@content) 53 | document.search('//img[@src]').each do |img| 54 | image_path = Pathname.new(img['src']) 55 | 56 | if image_path.relative? 57 | @assets << Asset.new(img['src']) 58 | end 59 | end 60 | end 61 | end 62 | end 63 | end 64 | -------------------------------------------------------------------------------- /lib/swift/playground/util/pipeline/section_filter.rb: -------------------------------------------------------------------------------- 1 | require 'html/pipeline' 2 | 3 | module Swift::Playground::Util 4 | class Pipeline 5 | class SectionFilter < HTML::Pipeline::Filter 6 | def call 7 | # Solution derived from http://stackoverflow.com/a/4799902 8 | children = doc.children # Every immediate child of the doc 9 | doc.inner_html = '' # Empty the doc now that we have our nodes 10 | 11 | # Comments preceding a swift code section can have meaning, so we need 12 | # to track the last comment made: 13 | last_comment = nil 14 | section = new_section(doc) # Create our first container in the doc 15 | children.each do |node| 16 | if node.name == 'comment' 17 | last_comment = node.content.strip 18 | elsif node.name == 'pre' && node[:lang] == 'swift' && last_comment != 'IGNORE' 19 | # If this code is the first thing in the document then the previous 20 | # section will be empty and the only child of the document, so we 21 | # should remove it: 22 | section.remove if section.content.empty? && doc.children.count == 1 23 | 24 | swift_section = new_section(doc, role: 'code') 25 | swift_section[:title] = last_comment unless last_comment.blank? 26 | node.remove_attribute('lang') 27 | swift_section << node 28 | 29 | section = new_section(doc) # Create a new container for subsequent nodes 30 | else 31 | last_comment = nil unless node.name == 'text' && node.content.blank? 32 | section << node 33 | end 34 | end 35 | section.remove if section.content.empty? # Get rid of a trailing, empty section 36 | 37 | doc 38 | end 39 | 40 | private 41 | 42 | def new_section(doc, attributes = {}) 43 | attributes = { 44 | role: 'documentation' 45 | }.merge(attributes) 46 | 47 | section = (doc << '

').children.last 48 | attributes.each do |attribute, value| 49 | section[attribute] = value 50 | end 51 | section 52 | end 53 | end 54 | end 55 | end 56 | -------------------------------------------------------------------------------- /lib/swift/playground/cli/ui.rb: -------------------------------------------------------------------------------- 1 | require 'highline/import' 2 | require 'paint' 3 | require 'forwardable' 4 | require 'active_support/core_ext/module' 5 | 6 | unless STDOUT.tty? 7 | # If we aren't using a TTY, then we need to avoid Highline attempting to set 8 | # TTY specific features (such as 'no echo mode'), as these will fail. We can 9 | # do so by monkey patching Highline to make the methods that peform these 10 | # functions no-ops: 11 | class HighLine 12 | module SystemExtensions 13 | def raw_no_echo_mode 14 | end 15 | 16 | def restore_mode 17 | end 18 | end 19 | end 20 | end 21 | 22 | Paint::SHORTCUTS[:swift_playground] = { 23 | :red => Paint.color(:red), 24 | :blue => Paint.color(:blue), 25 | :cyan => Paint.color(:cyan), 26 | :bright => Paint.color(:bright) 27 | } 28 | $paint = Paint::SwiftPlayground 29 | 30 | # Convenience module for accessing Highline features 31 | module Swift::Playground::CLI 32 | module UI 33 | extend SingleForwardable 34 | 35 | mattr_accessor :show_debug, :color_mode, :silence 36 | 37 | def_delegators :$terminal, :agree, :ask, :choose 38 | def_delegators :$paint, *Paint::SHORTCUTS[:swift_playground].keys 39 | 40 | class << self 41 | def say(message = "\n") 42 | return if silence 43 | 44 | terminal.say message 45 | end 46 | 47 | def error(message = nil, exception = nil) 48 | return if silence 49 | 50 | stderr.puts red(message) 51 | if exception && show_debug 52 | exception_details = ["Handled <#{exception.class}>:", 53 | exception.message, 54 | *exception.backtrace] 55 | stderr.puts red("\n" + exception_details.join("\n") + "\n") 56 | end 57 | end 58 | 59 | def debug(message = nil, &block) 60 | return if silence 61 | 62 | if show_debug 63 | message = formatted_log_message(message, &block) 64 | stderr.puts blue(message) 65 | end 66 | end 67 | 68 | def info(message = nil, &block) 69 | return if silence 70 | 71 | if show_debug 72 | message = formatted_log_message(message, &block) 73 | stderr.puts cyan(message) 74 | end 75 | end 76 | 77 | private 78 | 79 | def formatted_log_message(message = nil, &block) 80 | if block 81 | lines = block.call.split("\n") 82 | if message 83 | message = "#{message}: " 84 | message += "\n " if lines.count > 1 85 | message += lines.join("\n ") 86 | else 87 | message += lines.join("\n") 88 | end 89 | end 90 | 91 | message 92 | end 93 | 94 | def colorize(stream) 95 | case (color_mode || 'auto') 96 | when 'auto' 97 | if stream.tty? 98 | Paint.mode = Paint.detect_mode 99 | else 100 | Paint.mode = 0 101 | end 102 | when 'always' 103 | Paint.mode = Paint.detect_mode 104 | when 'never' 105 | Paint.mode = 0 106 | end 107 | end 108 | 109 | def terminal 110 | colorize($stdout) 111 | $terminal 112 | end 113 | 114 | def stderr 115 | colorize($stderr) 116 | $stderr 117 | end 118 | end 119 | end 120 | end 121 | -------------------------------------------------------------------------------- /lib/swift/playground/section.rb: -------------------------------------------------------------------------------- 1 | require 'pathname' 2 | 3 | module Swift 4 | class Playground 5 | sections_path = Pathname.new('swift/playground/sections') 6 | autoload :DocumentationSection, sections_path.join('documentation_section') 7 | autoload :CodeSection, sections_path.join('code_section') 8 | 9 | class Section 10 | include Util::SourceIO 11 | 12 | class TemplateContext 13 | attr_accessor :content, :number 14 | 15 | extend Forwardable 16 | def_delegators :@playground, :stylesheets, :javascripts 17 | 18 | def self.context(*args) 19 | new(*args).instance_eval { binding } 20 | end 21 | 22 | def context 23 | binding 24 | end 25 | 26 | def initialize(content, number, playground) 27 | @content = content 28 | @number = number 29 | @playground = playground 30 | end 31 | end 32 | 33 | attr_reader :content 34 | 35 | class << self 36 | protected 37 | 38 | def template 39 | unless defined? @template 40 | template_root = Pathname.new('../template').expand_path(__FILE__) 41 | template_path = template_root.join(@directory, "section.#{@extension}.erb") 42 | 43 | if template_path.exist? 44 | template_contents = template_path.read 45 | else 46 | template_contents = '<%= content %>' 47 | end 48 | @template = ERB.new(template_contents) 49 | end 50 | 51 | @template 52 | end 53 | 54 | def extension(extension = nil) 55 | @extension = extension unless extension.nil? 56 | @extension 57 | end 58 | 59 | def directory(path = nil) 60 | @directory = Pathname.new(path || '') unless path.nil? 61 | @directory 62 | end 63 | 64 | def xcplayground(options = nil) 65 | @xcplayground_options = options unless options.nil? 66 | @xcplayground_options 67 | end 68 | end 69 | 70 | def initialize(content) 71 | @content = source_as_io(content).read 72 | @content.freeze 73 | end 74 | 75 | def filename(number) 76 | "section-#{number}.#{extension}" 77 | end 78 | 79 | def path(number) 80 | directory.join filename(number) 81 | end 82 | 83 | def xcplayground_node(number) 84 | options = xcplayground_options 85 | 86 | node = Nokogiri::XML.fragment("<#{options[:node]}>").children.first 87 | node[options[:path_attribute]] = path(number).relative_path_from(directory) 88 | node 89 | end 90 | 91 | def render(number, playground, custom_content = nil) 92 | context = TemplateContext.context custom_content || content, 93 | number, 94 | playground 95 | template.result(context) 96 | end 97 | 98 | protected 99 | 100 | def template 101 | self.class.send(:template) 102 | end 103 | 104 | def extension 105 | self.class.send(:extension) 106 | end 107 | 108 | def directory 109 | self.class.send(:directory) 110 | end 111 | 112 | def xcplayground_options 113 | self.class.send(:xcplayground) 114 | end 115 | end 116 | end 117 | end 118 | -------------------------------------------------------------------------------- /lib/swift/playground/template/Documentation/defaults.css.scss: -------------------------------------------------------------------------------- 1 | $playground_font_family: "Helvetica Neue", Helvetica, sans-serif !default; 2 | $playground_font_size: 1.1rem !default; 3 | $playground_background_color: #fff !default; 4 | $playground_text_inset: 6px !default; 5 | 6 | $playground_section_separator_height: 1px !default; 7 | $playground_section_separator_color: #e7e7e7 !default; 8 | 9 | $playground_gutter_width: 28px !default; 10 | $playground_gutter_color: #fff !default; 11 | $playground_gutter_right_margin_inset: 8px !default; 12 | $playground_gutter_right_margin_line_width: 1px !default; 13 | $playground_gutter_right_margin_line_style: solid !default; 14 | $playground_gutter_right_margin_line_color: $playground_section_separator_color !default; 15 | 16 | // This font adjustment is so that 1rem of Menlo will appear the same size in 17 | // the HTML sections as it does in the editable swift code sections. For some 18 | // reason Xcode (6.1.1 - 6A2008a) adds 3 px to the font-size in HTML sections 19 | // when compared against the font-size used in those code sections. The 'calc' 20 | // using this adjustment variable compensates for this: 21 | $playground_font_adjustment: 3px !default; 22 | // This separator buffer is needed to avoid the bottom border of a section being 23 | // reduced by half a pixel sometimes. Instead a transparent 0.5-1px buffer 24 | // appears below the border which in practice looks better: 25 | $playground_section_separator_buffer: 1px !default; 26 | 27 | html { 28 | // Xcode (6.1.1 - 6A2008a) adds 3px to the font-size in HTML sections when 29 | // compared against the font-size used in the swift code sections. The 30 | // following 'calc' compensates for this, so 1 rem of Menlo in the HTML will 31 | // be the exact same size as code in the swift sections (using the default 32 | // Xcode themes that use the Menlo font): 33 | font-size: calc(1em - #{$playground_font_adjustment}) ; 34 | margin: 0; 35 | padding: 0; 36 | } 37 | 38 | body { 39 | position: relative; 40 | overflow: hidden; 41 | margin: 0; 42 | box-sizing: border-box; 43 | 44 | font-family: $playground_font_family; 45 | font-size: $playground_font_size; 46 | 47 | @if $playground_section_separator_buffer > 0 { 48 | border-bottom: $playground_section_separator_buffer solid transparent; 49 | } 50 | 51 | background: transparent; 52 | 53 | > section { 54 | box-sizing: border-box; 55 | 56 | padding: 0 ($playground_gutter_width + $playground_text_inset); 57 | background: $playground_background_color; 58 | border: $playground_section_separator_height solid $playground_section_separator_color; 59 | border-width: $playground_section_separator_height 0; 60 | 61 | @media (max-height: ($playground_section_separator_height * 2) + 1) { 62 | border-bottom: none; 63 | } 64 | } 65 | 66 | > .gutter { 67 | display: block; 68 | position: absolute; 69 | left: 0; 70 | top: $playground_section_separator_height; 71 | bottom: $playground_section_separator_height; 72 | width: $playground_gutter_width; 73 | box-sizing: border-box; 74 | 75 | background: $playground_gutter_color; 76 | 77 | > .margin { 78 | display: block; 79 | position: absolute; 80 | right: 0; 81 | top: 0; 82 | bottom: 0; 83 | width: $playground_gutter_right_margin_inset; 84 | box-sizing: border-box; 85 | 86 | border-left: $playground_gutter_right_margin_line_width 87 | $playground_gutter_right_margin_line_style 88 | $playground_gutter_right_margin_line_color; 89 | } 90 | } 91 | } 92 | 93 | code, pre { 94 | font-family: Menlo, "Andale Mono", Monaco, monospace; 95 | font-size: 1rem; 96 | } 97 | -------------------------------------------------------------------------------- /lib/swift/playground/cli/commands/generate.rb: -------------------------------------------------------------------------------- 1 | module Swift::Playground::CLI 2 | module Commands 3 | module Generate 4 | extend Definition 5 | 6 | definition do 7 | desc 'Generate a playground file from the provided Markdown file' 8 | arg '' 9 | arg '', :optional 10 | command :generate do |c| 11 | c.extend SharedCreationSwitches 12 | 13 | c.flag :stylesheet, 14 | arg_name: '', 15 | type: String, 16 | desc: 'CSS stylesheet for the HTML documentation sections of the playground. SASS/SCSS syntax is supported. This will be included after the default stylesheet.' 17 | 18 | c.flag :javascript, 19 | arg_name: '', 20 | type: String, 21 | desc: 'A javascript file for the HTML documentation sections of the playground. Each section is rendered independently of another and the script will not have access to the DOM from any other sections.' 22 | 23 | c.switch :emoji, 24 | default_value: true, 25 | desc: "Convert emoji aliases (e.g. `:+1:`) into emoji characters." 26 | 27 | c.switch :highlighting, 28 | default_value: true, 29 | desc: "Detect non-swift code blocks and add syntax highlighting. Only has an effect if 'github-linguist' and 'pygments.rb' gems are installed." 30 | 31 | c.flag :'highlighting-style', 32 | arg_name: '