swift-playground 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 992b070655de9c6fc56513c9e7f94e1def404707
+  data.tar.gz: b5af362cd26b24bfc49335c2610a5812b79ba521
+SHA512:
+  metadata.gz: 2b797a867775fffa37d24eda66c247e49a146c2cb47cff74d62aa12a27fae38a757db3696d75f246202d3d7f1558418bb0115ea298f6b09c75a04ac51a572c9c
+  data.tar.gz: d1c125605c84a4ba04e7e6290b92240cd774ad127dc2e52b33daefab4a29487663bf9aefc94a2bbe01c76232269a0a49674337a7c5b23fc1e6b83c761dcce751

data/.gitignore

@@ -0,0 +1,14 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+*.bundle
+*.so
+*.o
+*.a
+mkmf.log

data/.ruby-version

@@ -0,0 +1 @@
+2.0.0

data/Gemfile

@@ -0,0 +1,19 @@
+source 'https://rubygems.org'
+
+gemspec
+
+gem 'rake'
+
+group :development do
+  # github-linguist requires charlock_holmes which is not an easy install, making
+  # this an optional dependency gives gem users the choice of whether to solve
+  # the problem of installing that gem in order to get syntax highlighting.
+  #
+  # pygments.rb can also be problematic on some platforms and also is used
+  # only for syntax highlighting so can be optional also:
+  gem 'github-linguist', '~> 4.3.1'
+  gem 'pygments.rb', '~> 0.6.0'
+
+  gem 'pry'
+  gem 'pry-byebug', '1.3.3'
+end

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Resolve Digital and Mark Haylock
+
+MIT License
+
+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,209 @@
+# Swift Playground
+
+Create and modify Xcode Swift Playgrounds from Ruby. Includes both a Ruby API and a CLI.
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+## Contents
+
+- [Installation](#installation)
+- [CLI Usage](#cli-usage)
+  - [Creating an empty playground](#creating-an-empty-playground)
+  - [Generate a playground from markdown](#generate-a-playground-from-markdown)
+- [Ruby Usage](#ruby-usage)
+  - [Constructing a basic playground](#constructing-a-basic-playground)
+  - [Generating a playground from markdown](#generating-a-playground-from-markdown)
+  - [Sections](#sections)
+- [Markdown Format](#markdown-format)
+- [Default Stylesheet](#default-stylesheet)
+- [Credits](#credits)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+## Installation
+
+Install via RubyGems:
+```
+$ gem install playground
+```
+
+## CLI Usage
+
+### Creating an empty playground
+
+The playground created is the same as as Xcode would via "File > New > Playground…":
+```
+$ swift-playground new [options] example.playground
+```
+
+This command supports these options (see `swift-playground help new`):
+
+* __`--platform=[ios|osx]`__
+
+    The target platform for the generated playground (default: ios).
+* __`--[no-]reset`__
+
+    Allow the playground to be reset to it's original state via "Editor > Reset Playground" in Xcode (default: enabled).
+* __`--open`__
+
+    Open the playground in Xcode once it has been created.
+
+### Generate a playground from markdown
+
+```
+$ swift-playground generate [options] example.md
+```
+
+This command supports the following options (see `swift-playground help generate`) in addition to the options supported by the `new` command that are detailed above:
+
+* __`--stylesheet=<file>`__
+
+    CSS stylesheet for the HTML documentation sections of the playground. [SASS/SCSS syntax](http://sass-lang.com) is supported. This will be included after the default stylesheet. (default: none).
+* __`--javascript=<file>`__
+
+    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 (default: none).
+* __`--[no-]reset`__
+
+    Allow the playground to be reset to it's original state via "Editor > Reset Playground" in Xcode (default: enabled).
+* __`--open`__
+
+    Open the playground in Xcode once it has been created.
+* __`--[no-]emoji`__
+
+    Convert emoji aliases (e.g. `:+1:`) into emoji characters (default: enabled).
+* __`--[no-]highlighting`__
+
+    Detect non-swift code blocks and add syntax highlighting. Only has an effect if '[github-linguist](https://github.com/github/linguist)' and '[pygments.rb](https://github.com/tmm1/pygments.rb)' gems are installed. (default: enabled).
+* __`--highlighting-style=<style>`__
+
+    The name of a pygments (http://pygments.org/) style to apply to syntax highlighted code blocks. Set to 'custom' if providing your own pygments-compatible stylesheet. Ignored if `--no-highlighting` is set. (default: default).
+
+## Ruby Usage
+
+_WARNING: This is still under development and the API may change before 1.0 is released._
+
+### Constructing a basic playground
+
+```ruby
+require 'swift/playground'
+
+playground = Swift::Playground.new
+
+documentation = Swift::Playground::DocumentationSection.new <<-HTML
+<h1>Welcome to the Playground!</h1>
+<p>
+  This is an <em>awesome</em> example playground!
+</p>
+HTML
+
+code = Swift::Playground::CodeSection.new <<-SWIFT
+// Write swiftly!
+
+import UIKit
+
+var str = "This string has contents."
+SWIFT
+
+playground.sections << documentation
+playground.sections << code
+
+playground.save('~/example.playground')
+```
+
+### Generating a playground from markdown
+
+```ruby
+require 'swift/playground/generator'
+
+playground = Swift::Playground::Generator.generate(markdown_file)
+```
+
+### Sections
+
+There are two section types you can use to construct a playground in Ruby:
+
+#### `DocumentationSection`
+
+These contain HTML that is rendered within the playground. You can construct a `DocumentationSection` with either a path to an HTML file or the raw HTML content itself (either as a String or an IO object):
+
+```ruby
+# All of the following are valid values for content:
+content = '/path/to/file.html'
+content = Pathname.new('/path/to/file.html')
+content = File.open('/path/to/file.html')
+content = <<-HTML
+  <h1>An example HTML fragment</h1>
+  <p>
+    Note this is a fragment, it does not have a root 'html' or 'body' tag.
+  </p>
+HTML
+
+# Creating the section:
+section = Swift::Playground::DocumentationSection.new(content)
+
+# Adding the section to a playground:
+playground.sections << section
+# or perhaps:
+playground.sections.insert(0, section)
+```
+
+The content you provide _must_ be an HTML fragment - if a `<html>`, `<head>` or `<body>` tag is present an exception will be raised.
+
+#### `CodeSection`
+
+These contain the executable swift code, and each playground must contain at least one of these sections. Constructing these sections is the same as `DocumentationSection` - you can use either a path to a swift file, or the raw swift code itself (either as a String or an IO object):
+
+```ruby
+# All of the following are valid values for content:
+content = '/path/to/file.swift'
+content = Pathname.new('/path/to/file.swift')
+content = File.open('/path/to/file.swift')
+content = <<-SWIFT
+  // Write swiftly!
+
+  import UIKit
+
+  var str = "This string has contents."
+SWIFT
+
+# Creating the section:
+section = Swift::Playground::CodeSection.new(content)
+
+# Set the 'style' of the section. Apple only document 'setup' at the
+# moment and this is all that is supported.
+#
+# 'setup' will wrap the section in a "Setup" label that can be toggled
+# (and initially appears minimized):
+section.style = 'setup'
+
+# Adding the section to a playground:
+playground.sections << section
+# or perhaps:
+playground.sections.insert(0, section)
+```
+
+## Markdown Format
+
+Generating a playground from Markdown supports the [Github Flavoured Markdown](https://help.github.com/articles/github-flavored-markdown/) syntax.
+
+## Default Stylesheet
+
+Each documentation section is generated with a [default stylesheet](lib/swift/playground/template/Documentation/defaults.css.scss) loaded before any custom stylesheet. This stylesheet aims to provide an improved baseline over what is already there from the webkit renderer's agent stylesheets.
+
+It does so in some specific ways:
+  1. The default font size is adjusted so that at `1rem` the default Xcode font "Menlo" will render at exactly the same size as it would in the swift code sections of the playground. This is true even if the user has changed the editor font size.
+  2. A "gutter" (`body > .gutter`) is added that renders a line where the editor gutter appears in Xcode when line numbers are disabled. When Line numbers are visible it will appear centered with the line numbers.
+  3. The main body of the section (`body > section`) has a left and right padding that aligns the text with the left hand margin of swift code sections.
+  4. Sets the default font of `<code>` and `<pre>` elements to "Menlo" which matches with the current default Xcode font.
+
+_Warning: These features rely on aspects of the Xcode interface the could change in future versions: the width of the editor gutter and the default size of the font inside of HTML documentation sections. There are no guarantees that these will stay the same between Xcode versions._
+
+_Be particularly cautious with adding color to the gutter, those colors may clash with the real gutter in the swift code sections - depending on the Theme being used by the user._
+
+## Credits
+
+Initial development by [Mark Haylock](https://github.com/mhaylock). Development sponsored by [Resolve Digital](http://resolve.digital).
+
+This work was originally inspired by the work of [Jason Sandmeyer](https://github.com/jas) (created [Playground](https://github.com/jas/playground) using Node.js) and [Sam Soffes](https://github.com/soffes) (created [Playground](https://github.com/soffes/playground) using Ruby) - thank you to you both!
+
+Thank you to [Amanda Wagener](https://github.com/awagener) for some pair programming assistance at [Rails Camp NZ 5](http://railscamps.com).

data/Rakefile

@@ -0,0 +1,16 @@
+module Bundler
+  class GemHelper
+    def perform_git_push_with_clean_env(options = '')
+      # Using a clean ENV ensures that ruby-based git credential helpers
+      # such as that used by boxen will still work:
+      Bundler.with_clean_env do
+        perform_git_push_without_clean_env(options)
+      end
+    end
+
+    alias_method :perform_git_push_without_clean_env, :perform_git_push
+    alias_method :perform_git_push, :perform_git_push_with_clean_env
+  end
+end
+
+require 'bundler/gem_tasks'

data/bin/swift-playground

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+require 'swift/playground'
+require 'swift/playground/cli'
+
+exit Swift::Playground::CLI.run(ARGV)

data/lib/swift/playground.rb

@@ -0,0 +1,193 @@
+require 'fileutils'
+require 'tmpdir'
+
+require 'swift/playground/metadata'
+require 'swift/playground/debug'
+require 'swift/playground/generator'
+require 'swift/playground/section'
+require 'swift/playground/asset'
+
+module Swift
+  class Playground
+    class TemplateContext
+      extend Forwardable
+      def_delegators :@playground, :sdk, :allows_reset?, :sections
+
+      def self.context(*args)
+        new(*args).instance_eval { binding }
+      end
+
+      def initialize(playground)
+        @playground = playground
+      end
+    end
+
+    attr_accessor :platform, :allow_reset, :convert_emoji, :syntax_highlighting
+    attr_accessor :sections, :stylesheets, :javascripts
+
+    class << self
+      protected
+
+      def template_path(*filenames)
+        template_root = Pathname.new('../playground/template').expand_path(__FILE__)
+        template_root.join(*filenames)
+      end
+
+      def xcplayground_template
+        unless defined? @template
+          template_path = template_path('contents.xcplayground.erb')
+          @template = ERB.new(template_path.read)
+        end
+
+        @template
+      end
+    end
+
+    def initialize(options = {})
+      self.sections = []
+      self.stylesheets = []
+      self.javascripts = []
+
+      stylesheet_path = template_path 'Documentation', 'defaults.css.scss'
+      self.stylesheets << Stylesheet.new(stylesheet_path)
+
+      options = {
+        platform: 'ios',
+        allow_reset: true,
+        convert_emoji: true,
+        syntax_highlighting: true
+      }.merge(options)
+
+      self.platform = options[:platform]
+      self.allow_reset = options[:allow_reset]
+      self.convert_emoji = options[:convert_emoji]
+      self.syntax_highlighting = options[:syntax_highlighting]
+    end
+
+    def platform=(platform)
+      platform = platform.downcase
+      raise 'Platform must be ios or osx' unless %w(ios osx).include?(platform)
+      @platform = platform
+    end
+
+    def sdk
+      case platform.to_s
+      when 'ios'
+        'iphonesimulator'
+      when 'osx'
+        'macosx'
+      end
+    end
+
+    def allows_reset?
+      allow_reset == true
+    end
+
+    def convert_emoji?
+      convert_emoji == true
+    end
+
+    def save(destination_path)
+      destination_path = Pathname.new(destination_path).expand_path
+
+      validate! destination_path
+
+      insert_highlighting_stylesheet
+
+      # Create playground in a temporary directory before moving in place of
+      # any existing playground. This avoids any partially written playground
+      # files being re-loaded by Xcode:
+      temp_path = Pathname.new(Dir.mktmpdir)
+      write_stylesheets(temp_path)
+      write_javascripts(temp_path)
+      write_sections(temp_path)
+      write_xcplayground(temp_path)
+
+      FileUtils.rm_rf(destination_path) if destination_path.exist?
+      FileUtils.mv(temp_path, destination_path)
+    ensure
+      remove_highlighting_stylesheet
+      FileUtils.remove_entry_secure(temp_path) if temp_path && temp_path.exist?
+    end
+
+    private
+
+    def validate!(destination_path)
+      unless destination_path.extname == '.playground'
+        raise "Destination path '#{destination_path} does not end in .playground."
+      end
+
+      unless sections.detect { |section| section.is_a?(CodeSection) }
+        raise 'A playground must have at least one code section.'
+      end
+    end
+
+    def insert_highlighting_stylesheet
+      if syntax_highlighting && Util::SyntaxHighlighting.available?
+        style = if syntax_highlighting == true
+          'default'
+        else
+          syntax_highlighting
+        end
+
+        unless style == 'custom'
+          @highlighting_css = Stylesheet.new(Util::SyntaxHighlighting.css(style),
+                                             filename: 'highlighting')
+          self.stylesheets.insert(0, @highlighting_css)
+        end
+      end
+    end
+
+    def remove_highlighting_stylesheet
+      if @highlighting_css
+        self.stylesheets.delete(@highlighting_css)
+        @highlighting_css = nil
+      end
+    end
+
+    def write_stylesheets(temp_path)
+      stylesheets_path = temp_path.join('Documentation')
+
+      stylesheets.each_with_index do |stylesheet, index|
+        number = index + 1
+        stylesheet.save(stylesheets_path, number)
+      end
+    end
+
+    def write_javascripts(temp_path)
+      javascripts_path = temp_path.join('Documentation')
+
+      javascripts.each_with_index do |javascript, index|
+        number = index + 1
+        javascript.save(javascripts_path, number)
+      end
+    end
+
+    def write_sections(temp_path)
+      sections.each_with_index do |section, index|
+        number = index + 1
+        path = temp_path.join(section.path number)
+
+        FileUtils.mkdir_p path.dirname
+        path.open('w') do |file|
+          file.write section.render(number, self)
+        end
+      end
+    end
+
+    def write_xcplayground(temp_path)
+      temp_path.join('contents.xcplayground').open('w') do |file|
+        context = TemplateContext.context(self)
+        file.write xcplayground_template.result(context)
+      end
+    end
+
+    def template_path(*filenames)
+      self.class.send(:template_path, *filenames)
+    end
+
+    def xcplayground_template
+      self.class.send(:xcplayground_template)
+    end
+  end
+end