squib 0.9.0 → 0.10.0

data/docs/learning.rst

@@ -0,0 +1,10 @@
+Learning Squib
+==============
+
+.. toctree::
+   :maxdepth: 1
+
+   guides/hello_world
+   guides/getting-started/index
+   guides/git
+   guides/game_icons

data/docs/make.bat

@@ -0,0 +1,263 @@
+@ECHO OFF
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set BUILDDIR=_build
+set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% .
+set I18NSPHINXOPTS=%SPHINXOPTS% .
+if NOT "%PAPER%" == "" (
+	set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS%
+	set I18NSPHINXOPTS=-D latex_paper_size=%PAPER% %I18NSPHINXOPTS%
+)
+
+if "%1" == "" goto help
+
+if "%1" == "help" (
+	:help
+	echo.Please use `make ^<target^>` where ^<target^> is one of
+	echo.  html       to make standalone HTML files
+	echo.  dirhtml    to make HTML files named index.html in directories
+	echo.  singlehtml to make a single large HTML file
+	echo.  pickle     to make pickle files
+	echo.  json       to make JSON files
+	echo.  htmlhelp   to make HTML files and a HTML help project
+	echo.  qthelp     to make HTML files and a qthelp project
+	echo.  devhelp    to make HTML files and a Devhelp project
+	echo.  epub       to make an epub
+	echo.  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter
+	echo.  text       to make text files
+	echo.  man        to make manual pages
+	echo.  texinfo    to make Texinfo files
+	echo.  gettext    to make PO message catalogs
+	echo.  changes    to make an overview over all changed/added/deprecated items
+	echo.  xml        to make Docutils-native XML files
+	echo.  pseudoxml  to make pseudoxml-XML files for display purposes
+	echo.  linkcheck  to check all external links for integrity
+	echo.  doctest    to run all doctests embedded in the documentation if enabled
+	echo.  coverage   to run coverage check of the documentation if enabled
+	goto end
+)
+
+if "%1" == "clean" (
+	for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i
+	del /q /s %BUILDDIR%\*
+	goto end
+)
+
+
+REM Check if sphinx-build is available and fallback to Python version if any
+%SPHINXBUILD% 1>NUL 2>NUL
+if errorlevel 9009 goto sphinx_python
+goto sphinx_ok
+
+:sphinx_python
+
+set SPHINXBUILD=python -m sphinx.__init__
+%SPHINXBUILD% 2> nul
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.http://sphinx-doc.org/
+	exit /b 1
+)
+
+:sphinx_ok
+
+
+if "%1" == "html" (
+	%SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The HTML pages are in %BUILDDIR%/html.
+	goto end
+)
+
+if "%1" == "dirhtml" (
+	%SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml.
+	goto end
+)
+
+if "%1" == "singlehtml" (
+	%SPHINXBUILD% -b singlehtml %ALLSPHINXOPTS% %BUILDDIR%/singlehtml
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The HTML pages are in %BUILDDIR%/singlehtml.
+	goto end
+)
+
+if "%1" == "pickle" (
+	%SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished; now you can process the pickle files.
+	goto end
+)
+
+if "%1" == "json" (
+	%SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished; now you can process the JSON files.
+	goto end
+)
+
+if "%1" == "htmlhelp" (
+	%SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished; now you can run HTML Help Workshop with the ^
+.hhp project file in %BUILDDIR%/htmlhelp.
+	goto end
+)
+
+if "%1" == "qthelp" (
+	%SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished; now you can run "qcollectiongenerator" with the ^
+.qhcp project file in %BUILDDIR%/qthelp, like this:
+	echo.^> qcollectiongenerator %BUILDDIR%\qthelp\Squib.qhcp
+	echo.To view the help file:
+	echo.^> assistant -collectionFile %BUILDDIR%\qthelp\Squib.ghc
+	goto end
+)
+
+if "%1" == "devhelp" (
+	%SPHINXBUILD% -b devhelp %ALLSPHINXOPTS% %BUILDDIR%/devhelp
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished.
+	goto end
+)
+
+if "%1" == "epub" (
+	%SPHINXBUILD% -b epub %ALLSPHINXOPTS% %BUILDDIR%/epub
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The epub file is in %BUILDDIR%/epub.
+	goto end
+)
+
+if "%1" == "latex" (
+	%SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished; the LaTeX files are in %BUILDDIR%/latex.
+	goto end
+)
+
+if "%1" == "latexpdf" (
+	%SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
+	cd %BUILDDIR%/latex
+	make all-pdf
+	cd %~dp0
+	echo.
+	echo.Build finished; the PDF files are in %BUILDDIR%/latex.
+	goto end
+)
+
+if "%1" == "latexpdfja" (
+	%SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
+	cd %BUILDDIR%/latex
+	make all-pdf-ja
+	cd %~dp0
+	echo.
+	echo.Build finished; the PDF files are in %BUILDDIR%/latex.
+	goto end
+)
+
+if "%1" == "text" (
+	%SPHINXBUILD% -b text %ALLSPHINXOPTS% %BUILDDIR%/text
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The text files are in %BUILDDIR%/text.
+	goto end
+)
+
+if "%1" == "man" (
+	%SPHINXBUILD% -b man %ALLSPHINXOPTS% %BUILDDIR%/man
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The manual pages are in %BUILDDIR%/man.
+	goto end
+)
+
+if "%1" == "texinfo" (
+	%SPHINXBUILD% -b texinfo %ALLSPHINXOPTS% %BUILDDIR%/texinfo
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The Texinfo files are in %BUILDDIR%/texinfo.
+	goto end
+)
+
+if "%1" == "gettext" (
+	%SPHINXBUILD% -b gettext %I18NSPHINXOPTS% %BUILDDIR%/locale
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The message catalogs are in %BUILDDIR%/locale.
+	goto end
+)
+
+if "%1" == "changes" (
+	%SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.The overview file is in %BUILDDIR%/changes.
+	goto end
+)
+
+if "%1" == "linkcheck" (
+	%SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Link check complete; look for any errors in the above output ^
+or in %BUILDDIR%/linkcheck/output.txt.
+	goto end
+)
+
+if "%1" == "doctest" (
+	%SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Testing of doctests in the sources finished, look at the ^
+results in %BUILDDIR%/doctest/output.txt.
+	goto end
+)
+
+if "%1" == "coverage" (
+	%SPHINXBUILD% -b coverage %ALLSPHINXOPTS% %BUILDDIR%/coverage
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Testing of coverage in the sources finished, look at the ^
+results in %BUILDDIR%/coverage/python.txt.
+	goto end
+)
+
+if "%1" == "xml" (
+	%SPHINXBUILD% -b xml %ALLSPHINXOPTS% %BUILDDIR%/xml
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The XML files are in %BUILDDIR%/xml.
+	goto end
+)
+
+if "%1" == "pseudoxml" (
+	%SPHINXBUILD% -b pseudoxml %ALLSPHINXOPTS% %BUILDDIR%/pseudoxml
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The pseudo-XML files are in %BUILDDIR%/pseudoxml.
+	goto end
+)
+
+:end

data/docs/parameters.rst

@@ -0,0 +1,26 @@
+Parameters are Optional
+=======================
+
+Squib is all about sane defaults and shorthand specification. Arguments to DSL methods are almost always using hashes, which look a lot like [Ruby 2.0's named parameters](http://www.ruby-doc.org/core-2.0.0/doc/syntax/calling_methods_rdoc.html#label-Keyword+Arguments). This means you can specify your parameters in any order you please. All parameters are optional.
+
+For example `x` and `y` default to 0 (i.e. the upper-left corner of the card). Any parameter that is specified in the command overrides any Squib defaults, `config.yml` settings, or layout rules.
+
+.. highlight:: none
+
+Note: you MUST use named parameters rather than positional parameters. For example: ``save :png`` will lead to an error like this::
+
+    C:/Ruby200/lib/ruby/gems/2.0.0/gems/squib-0.0.3/lib/squib/api/save.rb:12:in `save': wrong number of arguments (2 for 0..1) (ArgumentError)
+        from deck.rb:22:in `block in <main>'
+        from C:/Ruby200/lib/ruby/gems/2.0.0/gems/squib-0.0.3/lib/squib/deck.rb:60:in `instance_eval'
+        from C:/Ruby200/lib/ruby/gems/2.0.0/gems/squib-0.0.3/lib/squib/deck.rb:60:in `initialize'
+        from deck.rb:18:in `new'
+        from deck.rb:18:in `<main>'
+
+Instead, you must name the parameters: `save format: :png`
+
+.. warning::
+
+  If you provide an option to a DSL method that the DSL method does not recognize, Squib ignores the extraenous option without warning. For example, these two calls have identical behavior::
+
+    save_png prefix: 'front_'
+    save_png prefix: 'front_', narf: true

data/docs/server.bat

@@ -0,0 +1 @@
+sphinx-autobuild . _build/html

data/docs/text_feature.rst

@@ -0,0 +1,86 @@
+The Mighty text Method
+======================
+
+
+The :doc:`/dsl/text` method is a particularly powerful method with a ton of options. Be sure to check the option-by-option details in the DSL reference, but here are the highlights.
+
+Fonts
+-----
+
+To set the font, your ``text`` method call will look something like this::
+
+  text str: "Hello", font: 'MyFont Bold 32'
+
+
+The ``'MyFont Bold 32'`` is specified as a "Pango font string", which can involve `a lot of options <http://ruby-gnome2.osdn.jp/hiki.cgi?Pango%3A%3AFontDescription#Pango%3A%3AFontDescription.new>`_ including backup font families, size, all-caps, stretch, oblique, italic, and degree of boldness. (These options are only available if the underlying font supports them, however.) Here's are some :doc:`/dsl/text` calls with different Pango font strings::
+
+  text str: "Hello", font: 'Sans 18'
+  text str: "Hello", font: 'Arial,Verdana weight=900 style=oblique 36'
+  text str: "Hello", font: 'Times New Roman,Sans 25'
+
+
+Finally, Squib's ``text`` method has options such as ``font_size`` that allow you to override the font string. This means that you can set a blanket font for the whole deck, then adjust sizes from there. This is useful with layouts and ``extends`` too (see :doc:`/layouts`).
+
+.. note::
+
+  When the font has a space in the name (e.g. Times New Roman), you'll need to put a backup to get Pango's parsing to work. In some operating systems, you'll want to simply end with a comma::
+
+    text str: "Hello", font: 'Times New Roman, 25'
+
+.. note::
+
+  Most of the font rendering is done by a combination of your installed fonts, your OS, and your graphics card. Thus, different systems will render text slightly differently.
+
+Width and Height
+------------------
+
+By default, Pango text boxes will scale the text box to whatever you need, hence the ``:native`` default. However, for most of the other customizations to work (e.g. center-aligned) you'll need to specify the width. If both the width and the height are specified and the text overflows, then the ``ellipsize`` option is consulted to figure out what to do with the overflow. Also, the ``valign`` will only work if ``height`` is also set to something other than ``:native``.
+
+Hints
+-----
+
+Laying out text by typing in numbers can be confusing. What Squib calls "hints" is merely a rectangle around the text box. Hints can be turned on globally in the config file, using the :doc:`/dsl/hint` method, or in an individual text method. These are there merely for prototyping and are not intended for production. Additionally, these are not to be conflated with "rendering hints" that Pango and Cairo mention in their documentation.
+
+Extents
+------
+
+Sometimes you want size things based on the size of your rendered text. For example, drawing a rectangle around card's title such that the rectangle perfectly fits. Squib returns the final rendered size of the text so you can work with it afterward. It's an array of hashes that correspond to each card. The output looks like this::
+
+  Squib::Deck.new(cards: 2) do
+    extents = text(str: ['Hello', 'World!'])
+    puts extents
+  end
+
+will output::
+
+  [{:width=>109, :height=>55}, {:width=>142, :height=>55}] # Hello was 109 pixels wide, World 142 pixels
+
+Embedding Images
+------------------
+
+Squib can embed icons into the flow of text. To do this, you need to define text keys for Squib to look for, and then the corresponding files. The object given to the block is a ``TextEmbed``, which supports PNG and SVG. Here's a minimal example::
+
+  text(str: 'Gain 1 :health:') do |embed|
+    embed.svg key: ':health:', file: 'heart.svg'
+  end
+
+Markup
+------
+
+See :ref:`Markup <text-markup>` in  :doc:`/dsl/text`.
+
+Examples
+--------
+
+  * Examples of all of the above are crammed into the ``text_options.rb`` sample `found here <https://github.com/andymeneely/squib/tree/master/samples/text_options.rb>`_
+  * The ``embed_text.rb`` sample has more examples of embedding text, which can be `found here <https://github.com/andymeneely/squib/tree/master/samples/embed_text.rb>`_
+  * The ``config_text_markup.rb`` sample demonstrates how quoting can be configured, `found here <https://github.com/andymeneely/squib/tree/master/samples/config_text_markup.rb>`_
+
+And this one too:
+
+.. raw:: html
+
+  <script type="text/javascript" src="https://ajax.googleapis.com/ajax/libs/jquery/1.9.1/jquery.min.js"></script>
+  <script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/gist-embed/2.4/gist-embed.min.js"></script>
+  <code data-gist-id="52d7b8e332194946bc69" data-gist-file="_text.rb"></code>
+  <code data-gist-id="52d7b8e332194946bc69" data-gist-file="_text_00_expected.png"></code>

data/docs/units.rst

@@ -0,0 +1,6 @@
+Unit Conversion
+===============
+
+By default, Squib thinks in pixels. This decision was made so that we can have pixel-perfect layouts without automatically scaling everything, even though working in units is sometimes easier. We provide some conversion methods, including looking for strings that end in "in" and "cm" and computing based on the current DPI. The dpi is set on `Squib::Deck.new` (not `config.yml`).
+
+Example is in `samples/units.rb` found [here](https://github.com/andymeneely/squib/tree/master/samples/units.rb)

data/lib/squib.rb

@@ -2,10 +2,10 @@ require 'logger'
 require 'cairo'
 require 'pango'
 require 'rsvg2'
-require 'squib/version'
-require 'squib/commands/new'
-require 'squib/deck'
-require 'squib/card'
+require_relative 'squib/version'
+require_relative 'squib/commands/new'
+require_relative 'squib/deck'
+require_relative 'squib/card'
 
 module Squib
 

data/lib/squib/api/background.rb

@@ -1,15 +1,10 @@
+require_relative '../args/card_range'
+require_relative '../args/draw'
+
 module Squib
   class Deck
-    # Fills the background with the given color
-    # @example
-    #   background color: :white
-    #
-    # Options support Arrays, see {file:README.md#Arrays_and_Singleton_Expansion Arrays and Singleon Expansion}
-    #
-    # @option opts range [Enumerable] (:all) the range of cards over which this will be rendered. See {file:README.md#Specifying_Ranges Specifying Ranges}
-    # @option opts color [String] (:black) the color the font will render to. See {file:README.md#Specifying_Colors___Gradients Specifying Colors & Gradients}.
-    # @return [nil] nothing
-    # @api public
+
+    # DSL method. See http://squib.readthedocs.org
     def background(opts = {})
       range = Args::CardRange.new(opts[:range], deck_size: size)
       draw  = Args::Draw.new(custom_colors).load!(opts, expand_by: size, layout: layout, dpi: dpi)

data/lib/squib/api/data.rb

@@ -1,30 +1,12 @@
 require 'roo'
 require 'csv'
-require 'squib/args/input_file'
-require 'squib/args/import'
+require_relative '../args/input_file'
+require_relative '../args/import'
+require_relative '../args/csv_opts'
 
 module Squib
 
-  # Pulls Excel data from `.xlsx` files into a column-based hash
-  #
-  # Pulls the data into a Hash of arrays based on the columns. First row is assumed to be the header row.
-  # See the example `samples/excel.rb` in the [source repository](https://github.com/andymeneely/squib/tree/master/samples)
-  #
-  # @example
-  #   # Excel file looks like this:
-  #   # | h1 | h2 |
-  #   # ------------
-  #   # | 1  | 2  |
-  #   # | 3  | 4  |
-  #   data = xlsx file: 'data.xlsx', sheet: 0
-  #   => {'h1' => [1,3], 'h2' => [2,4]}
-  #
-  # @option opts file [String]  the file to open. Must end in `.xlsx`. Opens relative to the current directory.
-  # @option opts sheet [Integer] (0) The zero-based index of the sheet from which to read.
-  # @option opts strip [Boolean] (true) When true, strips leading and trailing whitespace on values and headers
-  # @option opts explode [String] ('qty') Quantity explosion will be applied to the column this name. See README for example.
-  # @return [Hash] a hash of arrays based on columns in the spreadsheet
-  # @api public
+  # DSL method. See http://squib.readthedocs.org
   def xlsx(opts = {})
     input = Args::InputFile.new(file: 'deck.xlsx').load!(opts)
     import = Args::Import.new.load!(opts)
@@ -32,47 +14,30 @@ module Squib
     s.default_sheet = s.sheets[input.sheet[0]]
     data = {}
     s.first_column.upto(s.last_column) do |col|
-      header = s.cell(s.first_row,col).to_s
+      header = s.cell(s.first_row, col).to_s
       header.strip! if import.strip?
       data[header] = []
       (s.first_row + 1).upto(s.last_row) do |row|
-        cell = s.cell(row,col)
+        cell = s.cell(row, col)
         # Roo hack for avoiding unnecessary .0's on whole integers (https://github.com/roo-rb/roo/issues/139)
-        cell = s.excelx_value(row,col) if s.excelx_type(row,col) == [:numeric_or_formula, 'General']
+        cell = s.excelx_value(row, col) if s.excelx_type(row, col) == [:numeric_or_formula, 'General']
         cell.strip! if cell.respond_to?(:strip) && import.strip?
         cell = yield(header, cell) if block_given?
         data[header] << cell
-      end#row
-    end#col
+      end# row
+    end# col
     explode_quantities(data, import.explode)
-  end#xlsx
+  end# xlsx
   module_function :xlsx
 
-  # Pulls CSV data from `.csv` files into a column-based hash
-  #
-  # Pulls the data into a Hash of arrays based on the columns. First row is assumed to be the header row.
-  # See the example `samples/csv.rb` in the [source repository](https://github.com/andymeneely/squib/tree/master/samples)
-  #
-  # @example
-  #   # File data.csv looks like this (without the comment symbols)
-  #   # h1,h2
-  #   # 1,2
-  #   # 3,4
-  #   data = csv file: 'data.csv'
-  #   => {'h1' => [1,3], 'h2' => [2,4]}
-  #
-  # Parsing uses Ruby's CSV, with options `{headers: true, converters: :numeric}`
-  # http://www.ruby-doc.org/stdlib-2.0/libdoc/csv/rdoc/CSV.html
-  #
-  # @option opts file [String]  the CSV-formatted file to open. Opens relative to the current directory.
-  # @option opts strip [Boolean] (true) When true, strips leading and trailing whitespace on values and headers
-  # @option opts explode [String] ('qty') Quantity explosion will be applied to the column this name. See README for example.
-  # @return [Hash] a hash of arrays based on columns in the table
-  # @api public
+  # DSL method. See http://squib.readthedocs.org
   def csv(opts = {})
-    file = Args::InputFile.new(file: 'deck.csv').load!(opts).file[0]
+    # TODO refactor all this out to separate methods, and its own class
     import = Args::Import.new.load!(opts)
-    table = CSV.read(file, headers: true, converters: :numeric)
+    file = Args::InputFile.new(file: 'deck.csv').load!(opts).file[0]
+    data = opts.key?(:data) ? opts[:data] : File.read(file)
+    csv_opts = Args::CSV_Opts.new(opts)
+    table = CSV.parse(data, csv_opts.to_hash)
     check_duplicate_csv_headers(table)
     hash = Hash.new
     table.headers.each do |header|
@@ -83,10 +48,20 @@ module Squib
     if import.strip?
       new_hash = Hash.new
       hash.each do |header, col|
-        new_hash[header] = col.map { |str| str = str.strip if str.respond_to?(:strip); str }
+        new_hash[header] = col.map do |str|
+          str = str.strip if str.respond_to?(:strip)
+          str
+        end
       end
       hash = new_hash
     end
+    if block_given?
+      hash.each do |header, col|
+        col.map! do |val|
+          yield(header, val)
+        end
+      end
+    end
     return explode_quantities(hash, import.explode)
   end
   module_function :csv
@@ -101,6 +76,7 @@ module Squib
   end
   module_function :check_duplicate_csv_headers
 
+  # @api private
   def explode_quantities(data, qty)
     return data unless data.key? qty.to_s.strip
     qtys = data[qty]
@@ -117,12 +93,12 @@ module Squib
 
   class Deck
 
-    # Convenience call on deck goes to the module function
+    # DSL method. See http://squib.readthedocs.org
     def xlsx(opts = {})
       Squib.xlsx(opts)
     end
 
-    # Convenience call on deck goes to the module function
+    # DSL method. See http://squib.readthedocs.org
     def csv(opts = {})
       Squib.csv(opts)
     end