sublime_dsl 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 5b577ed966febadd2751d13f7d5b16f8912d5306
+  data.tar.gz: b3f7a8b90827cffb1cdd42e68d38bd648ec67c37
+SHA512:
+  metadata.gz: d0ac519cf9c60fb106de04a6d72b894b63174d96cd3c176ed62f17a87a60a2832aba0ec80b4425496c97b7df3a7858d983444deb9e7631e975900df81e4560c4
+  data.tar.gz: f593fa22c1652903ba2b5c136d479ebd05178259b1e22906c9c37e976a78faf7715bb582261f9229c27039708cb1c6d17285bac0da2b298b87e32172244a0f63

data/README.md

@@ -0,0 +1,136 @@
+# Sublime DSL
+
+Configuration of Sublime Text using Ruby DSLs.
+
+## Motivation
+
+The configuration of Sublime Text uses horrible PList files (TextMate legacy),
+and verbose JSON files. I first used TextMate to develop grammars, but even there,
+typing grammars or specifying themes was a pain.
+
+So I had the idea to create a Ruby DSL for TextMate grammars, themes, etc.
+Once you have it, you wonder how you could do without it: all DSL statements
+are regular method calls, so you can use the power of Ruby instead of copy/paste,
+defining and calling your own methods.
+
+Refer to SYNTAX.md for more information on the DSLs.
+
+## Installation
+
+```
+$ gem install sublime_dsl
+```
+
+## Synopsis
+
+```
+$ subdsl import Ruby
+```
+
+This converts the Ruby package (from your ST packages directory) to a set of DSL files
+inside ./Ruby. You can then review and modify the files. Have a look at
+test/DSL.custom/Ruby.tmLanguage.rb for an example of refactoring (here-docs).
+Have a look at test/DSL.custom/SAS for a package created from
+scratch directly with the DSLs.
+
+```
+$ subdsl export Ruby
+```
+
+This converts the Ruby package in ./Ruby and places the files in the
+ST Ruby packages directory (the previous content as backed up into a
+zip archive).
+
+Type `subdsl help` for more info on the command.
+
+## Import: Converting to DSL
+
+When importing a ST package, some files are grouped into one DSL file:
+
+- all macros (*.sublime-macro) are grouped into macros.rb
+- all snippets (*.sublime-snippet, *.tmSnippet) are grouped into snippets.rb
+- all commands (*.sublime-commands) are grouped into commands.rb
+- all preferences (*.tmPreferences) are grouped into preferences.rb
+- all settings (*.sublime-settings) are grouped into settings.rb
+
+Other files generate one DSL file:
+
+- *.tmLanguage => *.tmLanguage.rb
+- *.sublime-menu => *.menu.rb
+- *.sublime-keymap => *.keymap.rb
+- *.sublime-mousemap => *.mousemap.rb
+
+Finally, files with an extension not listed above (e.g., *.py) are copied "as is".
+In particular, there is no DSL (yet?) for *.sublime-build and *.sublime-completions.
+
+## Export: Converting from DSL
+
+The export processes all *.rb files located in the DSL directory, and copies
+other files "as is". Therefore, the organization of DSL files is free: a whole
+package can be specified into one source file, or into several source files.
+
+## Tests
+
+I don't believe in unit tests. At least not at this stage, where I can change my mind
+and rework the API extensively. I do believe into extensive integration tests, so the
+tests are done as follows:
+
+- test/Packages.original and test/Packages.textmate contain the packages coming
+  from Sublime Text 2 and TextMate, respectively.
+
+- They were converted into DSL equivalents in test/DSL.original and test/DSL.textmate.
+
+- Then I tried to convert them back to PList/JSON packages into
+  test/Packages.original-round-trip and test/Packages.textmate-round-trip.
+
+- Everytime there was an error in the DSL (for instance because of illegal regular expressions),
+  I created a fixed DSL file in test/DSL.original-fixes or test/DSL.textmate-fixes, that is read
+  instead of the one in test/DSL.original or test/DSL.textmate, to allow round-tripping.
+
+- I then compared the result of the round-trip to the original, and checked it was OK.
+
+- I then fixed some warnings (FIXME comments in the grammar DSL files) and placed the result
+  in test/DSL.modified, exported them in test/Packages.modified, and checked the result.
+
+- I also created some tests using my French keyboard definition file, generating DSL in
+  test/DSL.original.kb-fr, and exporting them to test/Packages.original.kb-fr-round-trip.
+
+- Finally, I placed some custom DSL files in test/DSL.custom, with the export in
+  test/Packages.custom.
+
+So testing is simple and brute force: run `rake test`, and check that nothing changes,
+or that the changes are expected.
+
+## Contributing
+
+I welcome (constructive) criticism and ideas. This was an experience for me to create Ruby DSLs,
+and retrospectively, I'm even more impressed by Ruby. Many thanks to Matz for creating a language
+that makes programming a pleasure.
+
+The documentation is sparse, to say the least. Feel free to ask for clarifications:
+a heavy use of `method_missing` does not create an easy to understand piece of software.
+
+## License
+
+(The MIT License)
+
+Copyright (c) 2014 Thierry Lambert
+
+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/Rakefile

@@ -0,0 +1,248 @@
+# encoding: utf-8
+$VERBOSE = true
+$LOAD_PATH.unshift File.expand_path('./lib')
+require 'sublime_dsl'
+
+include SublimeDSL
+Console.set_ruby_verbosity = false
+
+undef rule if self.respond_to? :rule
+
+desc 'run a command'
+task 'cmd', 'arguments' do |t, args|
+  cmd = Dir['bin/*'].first
+  cmd << ' ' << args.arguments if args.arguments
+  puts cmd
+  system "ruby -w -Ilib #{cmd}"
+end
+
+desc 'build & install gem'
+task 'gem' do
+  system 'gem build sublime_dsl.gemspec'
+  system 'gem install sublime_dsl --local'
+end
+
+desc 'create RDoc documentation'
+task 'rdoc' do
+  require 'rdoc/rdoc'
+  # require 'rdoc/generator/babel'
+  FileUtils.rm_r 'doc' if File.directory?('doc')
+  rdoc = RDoc::RDoc.new
+  args = %w(--force-update --force-output --all)  # --hyperlink-all
+  args << '-f' << 'babel'
+  args << '-c' << 'utf-8'
+  args << '--see-standard-ancestors'
+  args << '-o' << 'doc'
+  args << '-t' << 'Sublime DSL'
+  args.concat %w(README.md SYNTAX.md lib)
+  rdoc.document(args)
+end
+
+desc 'run all tests'
+task 'test' do
+  Rake::Task['test:import'].invoke
+  Rake::Task['test:export'].invoke
+  Rake::Task['test:compare'].invoke
+end
+
+namespace 'test' do
+
+  desc 'import all packages to DSL'
+  task 'import', 'profile' do |t, args|
+
+    if args.profile
+      profiling('import', 'original') { import_packages 'original' }
+      profiling('import', 'keyboard') { import_packages 'original', true }
+      profiling('import', 'textmate') { import_packages 'textmate' }
+    else
+      import_packages 'original'
+      import_packages 'original', true
+      import_packages 'textmate'
+    end
+
+  end
+
+  desc 'import with custom keyboards'
+  task 'import_keyboards' do
+    import_packages 'original', true
+  end
+
+  desc 'export all DSL to packages'
+  task 'export', 'profile' do |t, args|
+    if args.profile then
+      profiling('export', 'original') { export_packages 'original' }
+      profiling('export', 'keyboard') { export_packages 'original.kb-fr' }
+      profiling('export', 'modified') { export_packages 'modified' }
+      profiling('export', 'textmate') { export_packages 'textmate' }
+      profiling('export', 'custom')   { export_packages 'custom' }
+    else
+      export_packages 'original'
+      export_packages 'original.kb-fr'
+      export_packages 'modified'
+      export_packages 'textmate'
+      export_packages 'custom'
+    end
+  end
+
+  desc 'export custom DSL packages'
+  task 'export_custom' do
+    export_packages 'custom'
+  end
+
+  desc 'compare JSON after round-trip'
+  task 'compare' do
+    compare 'original'
+  end
+
+end
+
+def sublime_dir
+  SublimeText.packages_dir
+end
+
+def capturing_stderr(file)
+  prev_stderr, $stderr = $stderr, File.open(file, 'wb:utf-8')
+  yield
+  $stderr.close
+ensure
+  $stderr = prev_stderr
+end
+
+def profiling(task, subtask)
+  require 'ruby-prof'
+  result = RubyProf.profile { yield }
+  profile_report "#{task}-#{subtask}", result
+end
+
+def profile_report(file, result)
+  printer = RubyProf::CallStackPrinter.new(result)
+  Dir.mkdir 'prof' unless File.directory?('prof')
+  File.open("prof/#{file}.html", 'wb') do |f|
+    printer.print f, title: file, application: 'Sublime DSL'
+  end
+end
+
+def import_packages(suffix, custom_keyboard = false)
+  inroot = "test/Packages.#{suffix}"
+  altroot = "test/Packages.#{suffix}-fixes"
+  altroot = nil unless File.directory?(altroot)
+  import_options = { root: inroot, alt_root: altroot }
+  write_options = {}
+  if custom_keyboard
+    suffix << '.kb-fr'
+    import_options[:include] = '*.sublime-keymap'
+    write_options[:keyboard] = 'AZERTY-fr-FR-v6 (Windows 7)'
+  end
+  outroot = "test/DSL.#{suffix}"
+  write_options.merge! root: outroot, backup: :never
+  log = "test/#{suffix}.import.log"
+  Console.verbosity = 0
+  Console.info "importing #{inroot}", true
+  capturing_stderr(log) do
+    dirs = Dir[inroot + '/*']
+    dirs.each.with_index(1) do |indir, index|
+      Console.progress index, dirs.length, indir, true
+      name = File.basename(indir)
+      p = SublimeText::Package.import(name, import_options)
+      p.write write_options if p
+    end
+  end
+end
+
+def export_packages(suffix)
+  inroot = "test/DSL.#{suffix}"
+  altroot = "test/DSL.#{suffix}-fixes"
+  outroot = "test/Packages.#{suffix}"
+  outroot << '-round-trip' unless suffix =~ /custom|modified/
+  read_options = { root: inroot }
+  read_options[:alt_root] = altroot if File.directory?(altroot)
+  export_options = { root: outroot, backup: :never, cleanup: true }
+  log = "test/#{suffix}.export.log"
+  Console.verbosity = 0
+  Console.info "exporting #{inroot}", true
+  capturing_stderr(log) do
+    dirs = Dir[inroot + '/*']
+    dirs.each.with_index(1) do |indir, index|
+      Console.progress index, dirs.length, indir, true
+      name = File.basename(indir)
+      p = SublimeText::Package.read(name, read_options)
+      p.export export_options if p
+    end
+  end
+end
+
+def compare(suffix)
+  extensions = 'macro,commands,menu,keymap,mousemap,settings,build,completions'
+  inroot = "test/Packages.#{suffix}"
+  altroot = "test/Packages.#{suffix}-fixes"
+  outroot = "test/Packages.#{suffix}-round-trip"
+  Dir[inroot + "/**/*.sublime-{#{extensions}}"].each do |infile|
+    indir = File.dirname(infile)
+    altdir = altroot + '/' << File.basename(indir)
+    altfile = altdir + '/' << File.basename(infile)
+    infile = altfile if File.exist?(altfile)
+    outdir = outroot + '/' << File.basename(indir)
+    outfile = outdir + '/' << File.basename(infile)
+    if File.exist?(outfile)
+      compare_json infile, outfile
+    else
+      # puts outfile
+      # puts '  no found'
+    end
+  end
+end
+
+def compare_json(infile, outfile)
+  in_text = File.read(infile, encoding: 'utf-8')
+  out_text = File.read(outfile, encoding: 'utf-8')
+  out_json = JSON[out_text]
+  if in_text.empty?
+    puts "*** mismatch: #{infile}" unless out_json.empty?
+    return
+  end
+  in_json = JSON[in_text]
+  normalize in_json
+  normalize out_json
+  return if in_json == out_json
+  puts "*** mismatch: #{infile}"
+  file = infile.gsub('/', '_')
+  File.open("#{file}.in", 'wb:utf-8') { |f| f.write JSON.pretty_generate(in_json) }
+  File.open("#{file}.out", 'wb:utf-8') { |f| f.write JSON.pretty_generate(out_json) }
+end
+
+def normalize(json)
+  case json
+  when Hash
+    h = {}
+    json.keys.sort.each do |k|
+      v = json[k]
+      normalize v
+      if k == 'mnemonic'
+        v = v.upcase
+      elsif k == 'keys' && v.is_a?(Array)
+        v = v.map do |spec|
+          *mods, key = spec.split(/\+(?!$)/)
+          if key == '+' || key == 'plus'
+            mods << 'shift'
+            key = '='
+          elsif key =~ /^(forward_slash|backquote|equals|minus)$/
+            map = { 'forward_slash' => '/', 'backquote' => '`', 'equals' => '=', 'minus' => '-' }
+            key = map[$1]
+          end
+          (mods.sort << key).join('+')
+        end
+      end
+      h[k] = v unless
+        (k == 'modifiers' && v.empty?) ||
+        (k == 'match_all' && v == false)
+    end
+    json.clear
+    json.merge! h
+  when Array
+    if json.all? { |e| e.is_a?(String) }
+      json.sort!
+    else
+      json.each { |e| normalize e }
+    end
+  end
+end