skeptick 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: f063a9fcc9653c7f7c10c975f1de9b5d7f1bfa85
-  data.tar.gz: bfe797cbb1dee5576f915765621ba3851bf949ed
+  metadata.gz: 92b23f5d9d5e194a4eed73a1a1422bd1a18de3c3
+  data.tar.gz: 1c7f34a26786c074d628d0cafe0aa14291b9a703
 SHA512:
-  metadata.gz: d44e20efd63cec1053b5f6e7f6fdfb91e28f53ffa00c80975f5fe187aaa8377be7f3825927bb64e9a357a0cff187f64fca07beae1f9152e8c72122963082bbdc
-  data.tar.gz: ec450c5a2a0ca862ca4e3ba04534f14d390e84e09e2e39bd6ff3da43dd216c9bf4abe9f8b911ccb50a55f6089e56cc9bbc37fe5acc66499fadc4a5f37f576014
+  metadata.gz: 31488ca6f7cc0988cabbb12f5e7ce049659bcf53d94aa333816e97bc6250db4fd29cfc15c38557bf3c3a5fbb20910bc2e7503b7b317addc79a46997f31a14a29
+  data.tar.gz: f67aa8409bbb944421876c4e6aa4b86d8515b8ea8b5fac36be9541657466b0974f0edd16062cc1d7fd4789af723dd93beb83a85fc56b73c78912c96f968a5e8c

data/CHANGELOG

@@ -1,3 +1,17 @@
+v0.2.0
+
+* No more aliased keywords (with, apply) only set, append, prepend
+* No more aliases: build, execute; only run
+* All strings are now escaped, so make sure you split arguments to `set`
+* Keyword `write` renamed to text (consistent with ImageMagick)
+* Keyword `save` is renamed to `write` (consistent with ImageMagick)
+* No more piping support (no point, use composition instead)
+* Blocks are now evaluated upon declaration (still without running the command)
+* It's now ok to assign convert to a variable that's also used inside the block
+* No more Image class, image method now aliased to convert
+* Sugar is implemented in a much more straightforward way
+* Code amount is significantly reduced
+
 v0.1.1
 
 * Add Skeptick.timeout (seconds) for limiting runtime of convert operations

data/README.md

@@ -1,12 +1,3 @@
-### A note on project status
-
-If looking at commits makes you think that this project is abandoned, it's not. Skeptick is being used in our production ever since its inception, and it's working great. The reason there is no new activity is as follows.
-
-* It's really working great for us
-* Nobody is submitting issues
-
-So don't let the lack of git activity fool you. I have plans to blog about some interesting use cases for Skeptick and link to them from this README, stay tuned.
-
 # Skeptick: Better ImageMagick for Ruby
 
 [![Build Status](https://travis-ci.org/maxim/skeptick.png?branch=master)](https://travis-ci.org/maxim/skeptick)
@@ -59,14 +50,14 @@ class MyClass
       # ...
     end
 
-    cmd.build
+    cmd.run
   end
 end
 ```
 
 The `cmd` object seen in above example can be inspected to see the exact command
 that Skeptick will run. Simply use `cmd.inspect` or `cmd.to_s`. Skeptick never
-runs anything until you call `build` (except for one very special case), so you
+runs anything until you call `run` (except for one very special case), so you
 can inspect commands all you want before executing them.
 
 If you don't want to require all of Skeptick, you can just require the core, and
@@ -74,8 +65,8 @@ and select any specific sugar you want.
 
 ```ruby
 require 'skeptick/core'
-require 'skeptick/sugar/resizing'
-require 'skeptick/sugar/composition'
+require 'skeptick/sugar/resized_image'
+require 'skeptick/sugar/compose'
 ```
 
 See the `lib/skeptick/sugar` dir for all the goodies.
@@ -103,115 +94,24 @@ obvious. Skeptick executes strings in your shell.
 
 ![Skeptick Logo](https://raw.github.com/maxim/skeptick/master/logo.png)
 
-This picture is produced with the following script
+Take a look at [logo.rb](logo.rb) to see thow this logo was generated.
 
-```ruby
-include Skeptick
-
-image_size = '400x120'
-left, top  = 8, 80
-
-# Build a picture with built-in tile:granite: texture and using the
-# skeptick-provided sugar method `rounded_corners_image`
-paper = rounded_corners_image(size: image_size, radius: 25) do
-  set   :size, image_size
-  image 'tile:granite:'
-  apply '-brightness-contrast', '38x-33'
-  apply :blur, '0x0.5'
-end
+A lot is going on in the above script, no worries, it's just a showcase. I bet
+the first thing you noticed is a shitstorm of little method names like `canvas`,
+`font`, `write`, `draw`, etc. Well, they are all sugar. We will cover sugar
+below.
 
-# Build a text image that says "Skeptick" using specified font, add gradient
-text = image do
-  canvas :none, size: '395x110'
-  font   'Handwriting - Dakota Regular'
-  set    :pointsize, 90
-  set    :fill, 'gradient:#37e-#007'
-  write  'Skeptick', left: left, top: top
-  apply  :blur, '0x0.7'
-end
-
-bezier = \
-  "#{left + 17 }, #{top + 17}   #{left + 457}, #{top - 13} " +
-  "#{left + 377}, #{top + 27}   #{left + 267}, #{top + 27}"
-
-# Draw a curve that will appear underneath the text using bezier coordinates
-curve = image do
-  canvas :none, size: '395x110'
-  set    :strokewidth, 2
-  set    :stroke, 'gradient:#37e-#007'
-  draw   "fill none bezier #{bezier}"
-end
-
-# Combine text and curve using `:over` blending, multiply it with paper using
-# `:multiply` blending, and add a torn effect using Skeptick-provided sugar
-# method `torn_paper_image`
-torn = torn_paper_image(
-  paper * (text + curve),
-  spread: 50,
-  blur:   '3x10'
-)
-
-# Create a convert command with all of the above and run it
-logo = convert(torn, to: "#{File.dirname(__FILE__)}/logo.png")
-logo.build
-
-# This is what the resulting command looks like
-# You can see it by running `logo.to_s`
-#
-# convert (
-#   (
-#     (
-#       -size 400x120 tile:granite:
-#       -brightness-contrast 38x-33 -blur 0x0.5
-#       (
-#         +clone -alpha transparent -background none
-#         -draw roundrectangle 1,1 400,120 25,25
-#       )
-#       -alpha set -compose dstin -composite
-#     )
-#
-#     (
-#       -size 395x110 canvas:none
-#       -font Handwriting---Dakota-Regular -pointsize 90
-#       -fill gradient:#37e-#007 -draw text 8,80 'Skeptick'
-#       -blur 0x0.7 -size 395x110 canvas:none -strokewidth 2
-#       -stroke gradient:#37e-#007
-#       -draw fill none
-#         bezier 25, 97   465, 67 385, 107   275, 107
-#       -compose over -composite
-#     )
-#
-#     -compose multiply -composite
-#   )
-#
-#   (
-#     +clone -alpha extract -virtual-pixel black -spread 50
-#     -blur 0x3 -threshold 50% -spread 1 -blur 0x.7
-#   )
-#
-#   -alpha off -compose copy_opacity -composite
-# ) logo.png
-
-```
-
-## All those little commands
-
-A lot of things happened in the above script, no worries, it's just a showcase.
-I bet the first thing you noticed is a shitstorm of little method names like
-`apply`, `canvas`, `font`, `write`, `draw`, etc. Well, they are all sugar. We
-will cover sugar later in teh given parchment.
-
-There are actually only three real commands in all of Skeptick: `convert`,
-`set`, and `image`.
+There are actually only 2 useful methods in all of Skeptick: `convert` and
+`set`.
 
 ### Convert
 
-`convert` can be used both outside and inside a transformation block. You could
-say for example this.
+`convert` can be used both standalone and inside another `convert`. You could
+say this.
 
 ```ruby
 command = convert('image1.png', to: 'image2.png') do
-  set '-resize', '200x200'
+  set :resize, '200x200'
 end
 
 # OUTPUT:
@@ -223,8 +123,8 @@ Or you could put it inside, and it will become a parenthesized subcommand.
 ```ruby
 command = convert('image1.png', to: 'image2.png') do
   convert do
-    set '+clone'          # pull in image1 into parentheses
-    set '-resize 100x100' # resize image1's clone in memory
+    set '+clone'           # pull in image1 into parentheses
+    set :resize, '100x100' # resize image1's clone in memory
   end
 
   set '-compose over'
@@ -254,131 +154,42 @@ end
 #   -resize 300x300 whatever.png
 ```
 
-See what I did there? It's composability. If you have a `convert` object in a
-variable, you can use it inside another `convert` object down the line.
-
-### Set
-
-`set` appends a string to your command. You can give it any arguments, it
-doesn't care, it will just `to_s` and concatenate them.
+See what I did there? The `command` from previous snippet is passed into
+`convert`. If you have a `convert` object in a variable, you can use it inside
+another `convert` object down the line. Nesting possibilities are endless.
 
+The same snippet could also be written like this.
 ```ruby
-# All same thing
-set '-resize 100x100'
-set '-resize', '100x100'
-set :resize, '100x100'
-```
-
-Yeah that last one is special convenience. If an argument to `set` is a symbol,
-it will convert it to `"-#{symbol}"`. If you need `+resize` type of thing you'd
-just have to use a string, or sugar, but later on that.
-
-### Image
-
-`image` is very similar to `convert`. However, `convert` is a command object
-that may contain many images, settings, operators, nested converts, etc. Image
-is also a command object that can contain many settings and operators, but it
-can only contain one image reference inside of it. The reference can be a path,
-a nested convert, or a special string representing a built-in imagemagick image,
-but it can be only one.
-
-```ruby
-command = convert(to: '/path/to/result.png') do
-  image '/path/to/image.png'
-  set :resize, '200x200'
-end
-
-# OUTPUT:
-# convert /path/to/image.png -resize 200x200 /path/to/result.png
-```
-
-In this case we declared an image inside a `convert` which references a path.
-Instead we could create an image that references a built-in image.
-
-```ruby
-command = convert(to: '/path/to/result.png') do
-  image 'rose:'
+new_command = convert(to: 'whatever.png') do
+  image command
+  set :resize, '300x300'
 end
-
-# OUTPUT:
-# convert rose: /path/to/result.png
-```
-
-You can save image objects in variables, and pass them around, but unlike
-`convert`, you cannot run them standalone.
-
-```ruby
-rose_image = image('rose:')
-command = convert(rose_image, to: '/path/to/result.png')
-
-# OUTPUT:
-# convert rose: /path/to/result.png
 ```
-See, we had to wrap it in a `convert` in order to use it. You could also append
-this image at any point inside the convert block.
 
-```ruby
-rose_image = image('rose:')
-command = convert(to: '/path/to/result.png') do
-  image rose_image
-end
+2 differences: 1 - instead of passing in `command` as argument we declare it
+inside the block. 2 - resize is a symbol. Any symbol passed into `set`
+automatically becomes a string with dash in front of it. Speaking of set.
 
-# OUTPUT:
-# convert rose: /path/to/result.png
-```
-
-As mentioned above, an image can come with its own settings and operators.
-
-```ruby
-rose_image = image do
-  set :background, 'transparent'
-  image 'rose:'
-  apply :resize, '200x200'
-end
-
-command = convert(to: '/path/to/result.png') do
-  image rose_image
-end
-```
-
-You could do all of this inline, the output will be the same.
-
-```ruby
-command = convert(to: '/path/to/result.png') do
-  image do
-    set :background, 'transparent'
-    image 'rose:'
-    apply :resize, '200x200'
-  end
-end
-
-# OUTPUT:
-# convert -background transparent rose: -resize 200x200 /path/to/result.png
-```
+### Set
 
-If you have a `convert` object you can pass it as an image too.
+`set` adds stuff to your command. You can give it any various arguments, it
+doesn't care.
 
 ```ruby
-saved_convert = convert(to: 'foo.png') do
-  image 'rose:'
-  set :resize, '200x200'
-end
-
-another_convert = convert(to: 'bar.png') do
-  image saved_convert
-  apply :blur, '0x0.5'
-end
-
-# OUTPUT
-# convert ( rose: -resize 200x200 ) -blur 0x0.5 bar.png
+# All same thing
+set '-resize 100x100'
+set '-resize', '100x100'
+set :resize, '100x100'
 ```
 
-Nesting possibilities are endless.
+In addition to `set` there are also `prepend` and `append` to put stuff at the
+beginning or end of a command, but they are rarely useful, and mostly for
+implementing your own sugar.
 
 ## Sugar
 
 Skeptick comes with a bunch of sugar. When you require Skeptick, you can simply
-require everything. This includes all the sugar.
+require everything. This includes all the sugar functionality.
 
 ```ruby
 require 'skeptick'
@@ -389,12 +200,12 @@ sugar you want.
 
 ```ruby
 require 'skeptick/core'
-require 'skeptick/sugar/composition'
+require 'skeptick/sugar/compose'
 ```
 
-### Composition Sugar
+### Compose Sugar
 
-Composition is sugar that adds `compose` shortcut to Skeptick's DSL.
+Compose is sugar that adds `compose` shortcut to Skeptick's DSL.
 
 ```ruby
 command = compose(:multiply, 'a.png', 'b.png', to: 'out.png') do
@@ -406,57 +217,46 @@ end
 ```
 
 It takes the blending type as the first argument, and injects some extra stuff
-into the resulting command, but really it's just a wrapper around `convert` as
-you could easily see in its implementation.
-
-```ruby
-def compose(blending, *args, &blk)
-  convert(*args, &blk).tap do |c|
-    c.append :compose, blending.to_s
-    c.append :composite
-  end
-end
-```
+into the resulting command.
 
-As usual, you don't have to list your images as method arguments like that.
+As with `convert`, you don't have to list your images as method arguments.
 Instead you could declare them inside the block using the `image` method. The
 following command does the same thing.
 
 ```ruby
 command = compose(:multiply, to: 'out.png') do
   image 'a.png'
-  image 'b.png'
+  convert 'b.png'
   set :resize, '200x200'
 end
 ```
 
+*Note:* `image` is alias of `convert`.
+
 Since most of Skeptick's power comes from the ability to infinitely nest things,
-here's a an example involving a nested `compose`.
+here's an example involving a nested `compose`.
 
 ```ruby
 command = convert('image1.png', to: 'result.png') do
   compose(:multiply) do
-    image 'image3.png[200x200]'
+    image 'image2.png[200x200]'
 
-    convert 'image4.png' do
+    convert 'image3.png' do
       set :unsharp, '0x5'
     end
-
   end
 end
 
 # OUTPUT:
 # convert
-#   image1.png ( image3.png[200x200] ( image4.png -unsharp 0x5 ) -compose
-#   multiply -composite ) result.png"
+#   image1.png image2.png[200x200] ( image3.png -unsharp 0x5 ) -compose
+#   multiply -composite result.png"
 ```
 
 Notice how we nest `compose` inside of `convert`, and then `convert` inside of
-`compose`. The output of each acts like any declared image. In other words,
-wherever you would write `image "foo.png"` you could also write a nested
-command.
+`compose`.
 
-### Composition Operators
+### Compose Operators
 
 This is more of a gimmick than a real feature, but you can use math operators
 like `+`, `-`, `*`, `/`, `&`, `|` to compose images. These are all based on
@@ -468,7 +268,7 @@ image2 = image('bar.png')
 result = convert(image1 * image2, to: 'baz.png')
 
 # OUTPUT:
-# convert ( foo.png bar.png -compose multiply -composite ) baz.png
+# convert foo.png bar.png -compose multiply -composite baz.png
 ```
 
 As you can see, this is equivalent of simply using `compose`.
@@ -478,9 +278,10 @@ As you can see, this is equivalent of simply using `compose`.
 result = compose(:multiply, 'foo.png', 'bar.png', to: 'baz.png')
 ```
 
-Check out `lib/skeptick/sugar/composition.rb` for what these operators do.
+Check out [lib/skeptick/sugar/compose.rb](lib/skeptick/sugar/compose.rb) for
+what these operators do.
 
-### Sequence Manipulation Sugar
+### clone, delete, swap
 
 Skeptick provides methods `clone`, `delete`, and `swap` to
 manipulate declared images in a sequence, just like in ImageMagick CLI.
@@ -540,58 +341,31 @@ sequence. Same with `swap` - you can provide two indexes in arguments like
 `swap(1,3)` to swap any 2 images in the sequence, or without arguments it'll
 act as `+swap` - which swaps last two images.
 
-### Debugging Sugar
+### Write
 
 Sometimes you might want to take a look at an intermediate image that's being
 generated inside parentheses, nested somewhere in your command. You can do so
-with the help of `save('/path/to/img.png')`, which is defined in
-`skeptick/sugar/debugging.rb`.
+with the help of `write '/path/to/img.png'`, which is defined in
+`skeptick/sugar/write.rb`.
 
 ```ruby
 command = convert(to: 'result.png') do
   compose(:multiply, 'a.png', 'b.png') do
-    save('~/Desktop/debug.png')
+    write '~/Desktop/debug.png'
   end
 
-  set '-resize', '200x200'
+  set :resize, '200x200'
 end
 ```
 
 In this case the result of inner `compose` command will be saved to desktop
-without affecting anything else. Again, this is a feature that already exists
-in ImageMagick, as becomes apparent from the resulting command.
+without affecting anything else. This is a feature that already exists in
+ImageMagick, as you can see for yourself from generated command:
 
     convert
       ( a.png b.png -compose multiply -composite -write ~/Desktop/debug.png )
       -resize 200x200 result.png
 
-## Chain
-
-This is rarely (if ever) needed, but with Skeptick you could easily create
-piped commands.
-
-```ruby
-command = chain(to: 'result.png') do
-  compose(:hardlight, 'a.png', 'b.png') do
-    set '-brightness-contrast', '2x4'
-  end
-
-  compose(:atop, 'c.png', :pipe)
-end
-
-# OUTPUT:
-# convert
-#   a.png b.png -compose hardlight -brightness-contrast 2x4 -composite miff:- |
-# convert
-#   c.png miff:- -compose atop -composite result.png
-```
-
-Two things to note here. First of all, commands that are declared in the `chain`
-block will become piped together. Second, we use a special `:pipe` symbol in
-the last `compose` command. This symbol indicates where the piped-in image
-should appear in the image sequence. You can see this in the output string. The
-`miff:-` appears after c.png, as expected.
-
 Documentation is to be continued...
 
 ## Contributing