hotcell 0.0.1 → 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 449b5df474465cb7aface35f5e960b944d3efb03
+  data.tar.gz: b0628e14925479f151259181106c924b57cf625e
+SHA512:
+  metadata.gz: fdd6e11a933a6d2ccba2e4e9f3cc82c291042d8f3c543f750e626f08626514a2b120d0453e4a7e4dc572a5a8faccd1332d02a4da368d12694e00481b1ef7c8f7
+  data.tar.gz: 29101765a3ddc4dc679ff59bddece44e18edf6314103dcb715984907b1cd3e493c8c2a4a639072e274e03408769b5dbbad31f19db8657f36087f3cbb655ed59b

data/.gitignore

@@ -16,4 +16,7 @@ test/tmp
 test/version_tmp
 tmp
 *.out
-*.dot
+*.dot
+.DS_Store
+.rbx
+*.bundle

data/.rspec

@@ -1,2 +1,3 @@
 --color
 --format progress
+--backtrace

data/.rvmrc

@@ -1 +1 @@
-rvm use 1.9.3@hotcell --create
+rvm use 2.0.0@hotcell --create

data/.travis.yml

@@ -0,0 +1,7 @@
+rvm:
+  - 1.9.3
+  - 2.0.0
+  - rbx-19mode
+  - rbx-20mode
+
+before_script: 'bundle exec rake project'

data/Gemfile

@@ -1,9 +1,12 @@
 source 'https://rubygems.org'
 
-# Specify your gem's dependencies in hotcell.gemspec
 gemspec
 
+gem 'rake'
+gem 'rake-compiler'
+
 gem 'awesome_print'
+# gem 'ruby-prof'
 
 group :test do
   gem 'rspec'

data/README.md

@@ -1,6 +1,16 @@
+[![Build Status](https://travis-ci.org/pyromaniac/hotcell.png)](https://travis-ci.org/pyromaniac/hotcell)
+
 # Hotcell
 
-TODO: Write a gem description
+Hotcell is a sanboxed template processor.
+
+Key features:
+
+* Ruby-like adult syntax, every expression returns its value
+* Ragel-based lexer + Racc-based parser = fast engine base
+* Stateless: once compiled - rendered as many times as nessesary
+* Safe and sandboxed. Template variables and functions are evaluated safely
+  and have no any access to the environment
 
 ## Installation
 
@@ -16,9 +26,358 @@ Or install it yourself as:
 
     $ gem install hotcell
 
+## Language reference
+
+Hotcell template consists of template parts and tags. Tags are enclosed in
+double curly braces `Hello, {{ name }}!`.
+Tags can contain expressions or commands. Expression is a combination of
+values and operators. Value can be an object, referenced by variable or
+a basic type.
+
+### Basic types
+
+Hotcell has several basic types:
+
+* Numbers: integer `{{ 42 }}` or float `{{ 36.6 }}`
+* Strings: single-quoted `{{ 'Hello' }}` or double-quoted `{{ "World" }}`.
+  Strings support escaping `{{ 'tlhab \'oS \'Iw HoHwI\' So\' batlh\' }}`.
+  Double-quoted strings also support escape sequences {{ "\n\r\s\t" }}
+* Regular expressions `{{ /Foo/i }}`. Simple. Expression plus options (imx)
+* Arrays `{{ [42, 'hello', /regex/m] }}`
+* Hashes `{{ { a: 42, b: 'bar' } }}` has js-like syntax, so only string
+  can be a key for a hash
+* Constant values `{{ true }}`, `{{ false }}`, `{{ nil }}` and `{{ null }}`.
+  Last two have the same meaning, use whatever you like.
+
+All the basic types are objects and support method calls on themselfs.
+
+### Variables
+
+Variable is a value reference (`{{ name }}`). Variable name is better
+to describe with regexp 
+
+```ruby
+/\[_a-z\]\[_a-z0-9\]*[?!]?/i
+```
+
+So `_` or `sum42?` - is a
+variable, but `123foo` - is not.
+
+### Operators
+
+Operators between values form an expression: `{{ forty_two = 6 * 7 }}` or
+`{{ [1, 2, 3].sum && true == 'wtf?' }}`
+
+1. Arithmetical:
+  * `+`, `-`, `*`, `/` are ordinary
+  * `%` means modulo
+  * `**` is the power
+2. Logical:
+  * `&&` - and, `||` - or, `!` - not
+  * `==` - equal and `!=` - inequal
+  * comparation: `>`, `>=`, `<`, `<=`
+3. Other:
+  * `=` for assigning (`{{ hello_string = 'Hello' }}`)
+  * `.` for method calling (`{{ 'hello'.strip }}`)
+  * `;` as an expressions delimiter (`{{ a = 'foo'; 3 == 7 }}`)
+  * `(` and `)` for operator precedence (`{{ (2 + 2) * 2 }}`) or
+    method arguments passing: `{{ hello(who, where) }}`
+  * `[]` is used for array or hash elements access (`{{ some_array[2] }}`
+    or `{{ [1, 2, 3][2] }}` or `{{ { foo: 'bar' }['foo'] }}`)
+
+Method call args are similar to ruby ones. You can call function like
+this: `{{ foo(42, 'string', opt1: 3, opt2: /regexp/) }}`, and the last
+argument would be a hash. Also parentheses are not required if function
+takes no arguments: `{{ foo.bar.baz }}` is similar to
+`{{ foo().bar().baz() }}`. Unlike ruby, in case of arguments presence,
+parentheses are required.
+
+### Expressions
+
+Hotcell supports multiline complex expressions. Only the last expression of
+an expression sequence will be returned. Expression delimeters are `;` or `\n`.
+
+```
+{{
+  forty_two = 6 * 7
+  sum = [1, 2, 3].sum;
+  (forty_two + sum) / 8
+}} {{# => 6 #}}
+```
+
+Feel free to combine operators, variables and objects - hotcell has
+really flexible expressions syntax.
+
+### Tags
+
+There is some tag modificators to set tag mode.
+
+* `!` - silence modificator. Prevents tag value to be concatenated with
+  template, so `{{! 42 }}` will return '' - empty string. This modificator
+  is useful for pre-calculation: `{{! var = 'foo' * 3 }}`.
+
+### Comments
+
+There is two comments types in Hotcell: in-tag line comment and block comment.
+
+#### In-tag line comments
+
+In-tag line comment works inside tag only. It starts from `#` symbol
+and finishes at the end of the line (`\n`):
+
+```
+{{
+  # here I will calculate number forty two
+  # with arithmetic operations help
+  6 * 7 # found!
+}}
+```
+
+#### Block comments
+
+Block comments are useful to enclose even tags:
+
+```
+{{# {{ 'string'.truncate(10) }} Template {{ nil || value }} #}}
+```
+
+### Commands
+
+Command is a special tag case. It is a logic of your template. It
+is more complex then function call and divided into two types:
+commands and blocks.
+
+Command syntax looks like this: `{{ [variable =] command_name [arg1, arg2...] }}`
+Unlike methods or functions call, command doesn't use parentheses to take
+arguments. Blocks are consist of command, closing tag and optional subcommands:
+
+```
+{{ [variable =] command_name [arg1, arg2...] }}
+  {{ subcommand [arg1, arg2...] }}
+{{ end command_name }} {{# or {{ endcommand_name }} #}}
+```
+
+Variable and assigment is optional and with it you can assign the
+command result to variable. For example, next command will put `Hello`
+string into `result` variable and concat nothing to template (because of
+the silence tag mode):
+
+```
+{{! result = if true }}
+  Hello
+{{ else }}
+  World
+{{ end if }}
+```
+
+#### Built-in Commands
+
+##### Include
+
+Include command renders and returns rendering result of another template
+into current.
+
+```
+{{ include 'template/path', name: 'Hulk' }}
+```
+
+Also additional local variables could be transferred to the included
+template via optional command hash.
+
+`Hotcell::Resolver` ancestors are used for template resolving. Default resolver
+stored in `Hotcell.resolver`, also resolver for current rendering could be
+set up via `:resolver` shared option:
+
+```ruby
+Hotcell::Template.parse('{{ include 'template' }}').render(shared: { resolver: MyResolver.new })
+```
+
+##### Cycle
+
+Command used for cycled output values from array. Useful with loops.
+
+```
+{{ for i, in: [1, 2, 3], loop: true }}
+  {{ i }} {{ cycle ['one', 'two', 'three'] }}{{ unless loop.last? }}, {{ end unless }}
+{{ end for }}
+```
+
+This will output `1 one, 2 two, 3 three`.
+
+#### Built-in Blocks
+
+##### If
+
+Conditional command. Like in most programming languages
+
+```
+{{ if var == 3 }}
+  foo
+{{ elsif !cool }}
+  bar
+{{ else }}
+  baz
+{{ end if }}
+```
+
+##### Unless
+
+Reversed conditional command. Sumilar to rubys. Only `else` subcommand is supported
+
+```
+{{ unless var == 3 }}
+  foo
+{{ else }}
+  bar
+{{ end unless }}
+```
+
+##### Case
+
+Case command. Like in most programming languages
+
+```
+{{ case 42 }}
+{{ when 42, 43 }}
+  foo
+{{ when value, 'string' }}
+  bar
+{{ else }}
+  baz
+{{ end case }}
+```
+
+##### For
+
+Loop command, first argument - variable to put next value, `in` option
+takes an array.
+
+```
+{{ for post, in: posts }}
+  {{ post.title }}
+{{ end for }}
+```
+
+Additional option `loop`. Takes `true` or `'string'`. Uses string as variable
+name to store loop options, in case of `true`, the default variable name is `'loop'`.
+
+```
+{{ for post, in: [1, 2, 3], loop: true }}
+{{# or {{ for post, in: [1, 2, 3], loop: 'forloop' }} #}}
+  {{ loop.index }}
+  {{# or {{ forloop.index }} #}}
+{{ end for }}
+```
+
+Full list of loop object methods:
+
+* `prev` - previous element of the array (nil if current is the first)
+* `next` - previous element of the array (nil if current is the last)
+* `length` or `size` or `count` - number, array length
+* `index` - current array value index, counting from 0
+* `rindex` - the same, but starting from the array tail
+* `first` or `first?` - boolean value, detect whether the current element is the first
+* `last` or `last?` - boolean value, detect whether the current element is the last
+
+##### Scope
+
+Block with encapsulated variables. Used for variables environment changing:
+
+```
+{{ scope count: 50, foo: some_value }}
+  {{ count }}
+  {{ foo }}
+{{ end scope }}
+```
+
+Or for template capturing:
+
+```
+{{! title = scope }}<h1>Hello</h1>{{ end scope }}
+{{ title }}
+```
+
 ## Usage
 
-TODO: Write usage instructions here
+### Basic usage:
+
+```ruby
+Hotcell::Template.parse('Hello, {{ name }}!').render name: 'Pyromaniac'
+```
+
+### Additional `render` options:
+
+* `:variables` - variables hash
+* `:environment` - environment variables hash
+* `:scope` - variables and environment variables together
+
+The main difference between environment and ordinary variables is: ordinary variables
+are accessible from the template and environment variables are not. Environment variables
+are user for official purposes, in tag, for example. At the options level, variables have
+string keys and environment variables have symbol keys.
+
+```ruby
+Hotcell::Template.parse('Hello, {{ name }}!').render(
+  variables: { name: 'Pyromaniac' },
+  environments: { some_access_token: '1234567890' },
+  scope: { 'foo' => 42, bar: 43 },
+  moo: 'Hello'
+)
+```
+
+So if you will use something like above, all three options will be merged, but `:variables`
+hash keys will be stringified, `:environment` hash keys will be symbolized, `:scope`
+hash will be lived as is and the rest non-official options will be stringified and used as
+variables. The result of this algorithm will be:
+
+```ruby
+{
+  'name' => 'Pyromaniac', 'foo' => 42, 'moo' => 'Hello',
+  some_access_token: '1234567890', bar: 43
+}
+```
+
+Remaining allowed options are:
+
+* `:rescuer` - a lambda for error rescuing logic. The result of lambda call will be joined to
+  the template. The default lambda just returns error message to the template.
+
+  ```ruby
+    Hotcell::Template.parse('Hello, {{ name }}!').render(
+      name: 'Pyromaniac',
+      rescuer: ->(e) { Rollbar.report_exception(e) }
+    )
+  ```
+
+* `:reraise` - raise exception after occurence or not. Error raises after `:rescuer` execution and
+  doesn't affect it. Accepts true or false.
+* `:helpers` - array of modules with fuctions accessible from template. `Hotcell.helpers` config
+  option is used by default. Works similar to ActionController's helpers.
+
+  ```ruby
+    Hotcell::Template.parse('Hello, {{ name }}!').render(
+      name: 'Pyromaniac',
+      helpers: MyHelper # or array [MyHelper1, MyHelper2]
+    )
+  ```
+* `:shared` - just hash of shared variables, for internal usage
+
+### Configuring Hotcell
+
+Hotcell has several configuration methods, which provide default internals for
+template processor proper work.
+
+* `commands` accessor returns a hash of default commands
+* `blocks` - same is for blocks
+* `helpers` - default helper modules array
+* `resolver` - default resolver for `include` command
+
+Also there are methods to setup configuration options:
+
+* `register_command` adds command or block to the list of default commands or blocks
+* `register_helpers` used for adding module to the list of helpers
+* `resolver=` setups new default resolver
+
 
 ## Contributing
 

data/Rakefile

@@ -1,17 +1,39 @@
-require "bundler/gem_tasks"
+require 'bundler/gem_tasks'
+require 'rake/extensiontask'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+Rake::ExtensionTask.new('lexerc') do |config|
+  config.lib_dir = 'lib/hotcell'
+end
+
+task :default => :spec
+
+desc 'Builds all the project'
+task :project do
+  %w(project:lexerr project:lexerc project:parser clobber compile).each do |task|
+    Rake::Task[task].invoke
+  end
+end
+
+namespace :project do
+  desc 'Build lexer'
+  task :lexerr do
+    `ragel -R -F1 lib/hotcell/lexerr.rl`
+  end
 
-namespace :build do
   desc 'Build lexer'
-  task :lexer do
-    `ragel -R -T0 lib/hotcell/lexer.rl`
+  task :lexerc do
+    `ragel -C -G2 ext/lexerc/lexerc.rl`
   end
 
   task :dot do
-    `ragel -Vp lib/hotcell/lexer.rl > lexer.dot`
+    `ragel -Vp lib/hotcell/lexerr.rl > lexerr.dot`
+    `ragel -Vp lib/hotcell/lexerc.rl > lexerc.dot`
   end
 
   desc 'Build parser'
   task :parser do
-    `racc -d -o lib/hotcell/parser.rb -O lib/hotcell/parser.out lib/hotcell/parser.y`
+    `racc -o lib/hotcell/parser.rb -O lib/hotcell/parser.out lib/hotcell/parser.y`
   end
 end

data/ext/lexerc/extconf.rb

@@ -0,0 +1,3 @@
+require 'mkmf'
+
+create_makefile('lexerc')