class Flooph

Create a new, reusable template parser and evaluator.

@param vars [Hash] symbol-to-values used in templates and conditional evaluations.

# File lib/flooph.rb, line 13
def initialize(vars={})
  super()
  @vars = vars
end

Evaluate an expression, looking up values and performing simple math.

f = Flooph.new cats:17, dogs:25
p f.calculate("cats + dogs")
#=> 42

@param vars [Hash] variable values to use for this and future evaluations.

If omitted, existing variable values will be used.
(see also #vars and #update_variables)

@return [Hash] the new variable values after updating.

# File lib/flooph.rb, line 122
def calculate(str, vars=nil)
  parse_and_transform(:value, str, vars)
end

Evaluate simple conditional expressions to a boolean value, with variable lookup. Examples:

cats?            # variable cats is set (and not set to `false` or `no`)
cats = 42        # variable `cats` equals 42
cats>0 & dogs>0  # if both variables are numbers greater than zero

• Numeric and string comparisons, using any of `< > = == ≤ <= ≥ >= ≠ !=`

  • Non-present variables or invalid comparisons always result in false

• Variable presence/truthiness using just name (isDead) or with optional trailing question mark (isDead?).

• Boolean composition, e.g. `a | b & c & (d | !e) || !(f && g)`

  • `!foo` means “not foo”, inverting the meaning

  • `&` has higher precedence than `|`

  • `|` is the same as `||`; `&` is the same as `&&`

@param vars [Hash] variable values to use for this and future evaluations.

If omitted, existing variable values will be used.
(see also #vars and #update_variables)

@return [true, false] the result of the evaluation.

# File lib/flooph.rb, line 76
def conditional(str, vars=nil)
  parse_and_transform(:boolean_expression, str, vars)
end

Common implementation for other methods @!visibility private

# File lib/flooph.rb, line 128
def parse_and_transform(root_rule, str, vars)
  @vars = vars if vars
  begin
    str = str.strip.gsub(/^[ \t]+|[ \t]+$/, '')
    tree = send(root_rule).parse(str)
    Transform.new.eval(tree, @vars)
  rescue Parslet::ParseFailed => error
    raise unless $DEBUG
    puts "Flooph failed to parse #{str.inspect}"
    puts error.parse_failure_cause.ascii_tree
    # TODO: catch transformation errors
  end
end

Evaluate a template like the following example, inserting content and evaluating conditional branches. If you don't supply `vars` then the existing values for the instance are used.

Hello, {=name}!                                # Insert values from variables.
                                               #
{?trollLocation="cave"}                        # Conditional based on boolean expressions.
There is a troll glaring at you.               # See #conditional for how to write conditions.
{|}                                            # Conditional 'else' clause.
The air smells bad here, like rotting meat.    #
{.}                                            # End of the if/else.
                                               #
{?debug}Troll is at {=trollLocation}.{.}       # Conditional based on if the variable exists (and isn't false)
                                               #
{?dogs>0}                                      #
I own {=dogs} dogg{?dogs=1}y{|}ies{.} now.     # Conditionals can be inline.
{.}                                            #
                                               #
{? cats=42 }                                   #
I have exactly 42 cats! I'll never get more.   #
{| cats=1 }                                    # Else-if for chained conditionals.
I have a cat. If I get another, I'll have two. #
{| cats>1 }                                    #
I have {=cats} cats.                           #
If I get another, I'll have {=cats+1}.         # Output can do simple addition/subtraction.
{|}                                            #
I don't have any cats.                         #
{.}                                            #

@param vars [Hash] variable values to use for this and future evaluations.

If omitted, existing variable values will be used.
(see also #vars and #update_variables)

@return [String] the template after transformation.

# File lib/flooph.rb, line 51
def transform(str, vars=nil)
  parse_and_transform(:mkup, str, vars).tap do |result|
    result.gsub!(/\n{3,}/, "\n\n") if result
  end
end

Parse a simple hash setup for setting and updating values. For example:

f = Flooph.new  # No variables yet
f.update_variables <<-END
  debug: false
  cats: 17
  alive: yes
  trollLocation: "cave"
END
f.conditional "cats > 3"
#=> true
f.update_variables "oldCats:cats \n cats: cats + 1"
f.calculate "cats"
#=> 18
f.calculate "oldCats"
#=> 17

Legal value types are:

• Booleans: `true`, `false`, `yes`, `no`

• Numbers: `-3`, `12`, `3.1415`

• Strings: `“foo”`, `“Old Barn”` _must use double quotes_

• Variables: `cats + 7` _only supports add/subtract, not multiplication_

@param vars [Hash] initial variable values to base references on.

If omitted, existing variable values will be used.

@return [Hash] the new variable values after updating.

# File lib/flooph.rb, line 107
def update_variables(str, vars=nil)
  parse_and_transform(:varset, str, vars)
  @vars
end