Necromancer

Conversion from one object type to another with a bit of black magic.

Necromancer provides independent type conversion component for TTY toolkit.

Motivation

Conversion between Ruby core types frequently comes up in projects but is solved by half-baked solutions. This library aims to provide an independent and extensible API to support a robust and generic way to convert between core Ruby types.

Features

• Simple and expressive API
• Ability to specify own converters
• Ability to compose conversions out of simpler ones
• Support conversion of custom defined types
• Ability to specify strict conversion mode

Installation

Add this line to your application's Gemfile:

gem "necromancer"

And then execute:

$ bundle

Or install it yourself as:

$ gem install necromancer

Contents

• 1. Usage
• 2. Interface
  • 2.1 convert
  • 2.2 from
  • 2.3 to
  • 2.4 can?
  • 2.5 configure
• 3. Converters
  • 3.1 Array
  • 3.2 Boolean
  • 3.3 DateTime
  • 3.4 Hash
  • 3.5 Numeric
  • 3.6 Range
  • 3.7 Custom
  • 3.7.1 Using an Object
  • 3.7.2 Using a Proc

1. Usage

Necromancer knows how to handle conversions between various types using the

convert

convert

to

>>

:symbol

object

ClassName

For example, to convert a string to a range type:

Necromancer.convert("1-10").to(:range)  # => 1..10
Necromancer.convert("1-10") >> :range   # => 1..10
Necromancer.convert("1-10") >> Range    # => 1..10

In order to handle boolean conversions:

Necromancer.convert("t").to(:boolean)   # => true
Necromancer.convert("t") >> true        # => true

To convert string to numeric value:

Necromancer.convert("10e1").to(:numeric)  # => 100

You can convert string to array of values like

boolean

integer

float

Necromancer.convert("t,f,t"]).to(:booleans)      # => [true, false, true]
Necromancer.convert("1,2.3,3.0"]).to(:integers)  # => [1, 2, 3]
Necromancer.convert("1,2.3,3.0"]).to(:floats)    # => [1.0, 2.3, 3.0]

To convert string to hash value:

Necromancer.convert("a:1 b:2 c:3").to(:hash) # => {a: "1", b: "2", c: "3"}
Necromancer.convert("a=1 b=2 c=3").to(:hash) # => {a: "1", b: "2", c: "3"}

To provide extra information about the conversion value type use the

from

Necromancer.convert(["1", "2.3", "3.0"]).from(:array).to(:numeric) # => [1, 2.3, 3.0]

Necromancer also allows you to add custom conversions.

When conversion isn't possible, a

Necromancer::NoTypeConversionAvailableError

convert

Necromancer.convert(:foo).to(:float)
# => Necromancer::NoTypeConversionAvailableError: Conversion 'foo->float' unavailable.

2. Interface

Necromancer will perform conversions on the supplied object through use of

convert

from

to

2.1 convert

For the purpose of divination, Necromancer uses

convert

Necromancer.convert("1,10").to(:range)  #  => 1..10

Alternatively, you can use block:

Necromancer.convert { "1,10" }.to(:range) # => 1..10

Conversion isn't always possible, in which case a

Necromancer::NoTypeConversionAvailableError

convert

Necromancer.convert(:foo).to(:float)
# => Necromancer::NoTypeConversionAvailableError: Conversion 'foo->float' unavailable.

2.2 from

To specify conversion source type use

from

Necromancer.convert("1.0").from(:string).to(:numeric)

In majority of cases you do not need to specify

from

convert

target

:numeric

convert

from

The source parameters are:

• :array

• :boolean

• :date

• :datetime

• :float

• :integer

• :numeric

• :range

• :string

• :time

2.3 to

To convert objects between types, Necromancer provides several target types. The

to

>>

:symbol

object

ClassName

Necromancer.convert("yes").to(:boolean)   # => true
Necromancer.convert("yes") >> :boolean    # => true
Necromancer.convert("yes") >> true        # => true
Necromancer.convert("yes") >> TrueClass   # => true

By default, when target conversion fails the original value is returned. However, you can pass

strict

Necromancer.convert("1a").to(:integer, strict: true)
# => raises Necromancer::ConversionTypeError

The target parameters are:

• :array

• :boolean

  ,

  :booleans

  ,

  :bools

  ,

  :boolean_hash

  ,

  :bool_hash

• :date

• :datetime

  ,

• :float

  ,

  :floats

  ,

  :float_hash

• :integer

  ,

  :integers

  ,

  :ints

  ,

  :integer_hash

  ,

  :int_hash

• :numeric

  ,

  :numerics

  ,

  :nums

  ,

  :numeric_hash

  ,

  :num_hash

• :range

• :string

• :time

2.4 can?

To verify that a given conversion can be handled by Necromancer call

can?

source

target

converter = Necromancer.new
converter.can?(:string, :integer)   # => true
converter.can?(:unknown, :integer)  # => false

2.5 configure

You may set global configuration options on Necromancer instance by passing a block like so:

Necromancer.new do |config|
  config.strict true
end

Or calling

configure

converter = Necromancer.new
converter.configure do |config|
  config.copy false
end

Available configuration options are:

• strict

  - ensures correct types for conversion, by default

  false

• copy

  - ensures only copy is modified, by default

  true

3. Converters

Necromancer flexibility means you can register your own converters or use the already defined converters for such types as

Array

Boolean

Date

DateTime

Hash

Numeric

Range

Time

3.1 Array

The Necromancer allows you to transform arbitrary object into array:

Necromancer.convert(nil).to(:array)     # => []
Necromancer.convert({x: 1}).to(:array)  # => [[:x, 1]]

In addition, Necromancer excels at converting

,

-

Necromancer.convert("a, b, c").to(:array)  # => ["a", "b", "c"]

If the string is a list of

-

,

Necromancer.convert("1 - 2 - 3").to(:array)  # => [1, 2, 3]

It handles conversion of string into an array of boolean values as well:

Necromancer.convert("yes,no,t").to(:booleans)    # => [true, false, true]
Necromancer.convert("1 - f - FALSE").to(:bools)  # => [true, false, false]

You can also convert array containing string objects to array containing numeric values:

Necromancer.convert(["1", "2.3", "3.0"]).to(:numerics) # => [1, 2.3, 3.0]
Necromancer.convert(["1", "2.3", "3.0"]).to(:nums)     # => [1, 2.3, 3.0]

Or you can be more specific by using

:integers

:floats

Necromancer.convert(["1", "2.3", "3.0"]).to(:integers) # => [1, 2, 3]

When in

strict

Necromancer::ConversionTypeError

Necromancer.convert(["1", "2.3", false]).to(:numerics, strict: true)
# => Necromancer::ConversionTypeError: false cannot be converted from `array` to `numerics`

However, in

non-strict

Necromancer.convert(["1", "2.3", false]).to(:numerics, strict: false)
# => [1, 2.3, false]

3.2 Boolean

The Necromancer allows you to convert a string object to boolean object. The

1

"1"

"t"

"T"

"true"

"TRUE"

"y"

"Y"

"yes"

"Yes"

"on"

"ON"

TrueClass

Necromancer.convert("yes").to(:boolean)  # => true

Similarly, the

0

"0"

"f"

"F"

"false"

"FALSE"

"n"

"N"

"no"

"No"

"off"

"OFF"

FalseClass

Necromancer.convert("no").to(:boolean) # => false

You can also convert an integer object to boolean:

Necromancer.convert(1).to(:boolean)  # => true
Necromancer.convert(0).to(:boolean)  # => false

3.3 DateTime

Necromancer knows how to convert string to

date

Necromancer.convert("1-1-2015").to(:date)    # => "2015-01-01"
Necromancer.convert("01/01/2015").to(:date)  # => "2015-01-01"

You can also convert string to

datetime

Necromancer.convert("1-1-2015").to(:datetime)          # => "2015-01-01T00:00:00+00:00"
Necromancer.convert("1-1-2015 15:12:44").to(:datetime) # => "2015-01-01T15:12:44+00:00"

To convert a string to a time instance do:

Necromancer.convert("01-01-2015").to(:time)       # => 2015-01-01 00:00:00 +0100
Necromancer.convert("01-01-2015 08:35").to(:time) # => 2015-01-01 08:35:00 +0100
Necromancer.convert("12:35").to(:time)            # => 2015-01-04 12:35:00 +0100

3.4 Hash

With Necromancer you can convert a string with pairs delimited by

=

:

Necromancer.convert("a:1 b:2 c:3").to(:hash)
Necromancer.convert("a=1 b=2 c=3").to(:hash)
# => {a: "1", b: "2", c: "3"}

The pairs can be separated by

&

=

:

Necromancer.convert("a:1 & b=2 & c:3").to(:hash)
# => {a: "1", b: "2", c: "3"}

You can also convert string to hash with integer values using

:int_hash

Necromancer.convert("a:1 b:2 c:3").to(:int_hash)     # => {a: 1, b: 2, c: 3}
Necromancer.convert("a:1 b:2 c:3").to(:integer_hash) # => {a: 1, b: 2, c: 3}

Similarly you can convert string to hash with

float

numeric

:float_hash

numeric_hash

Necromancer.convert("a:1 b:2 c:3").to(:float_hash)    # => {a: 1.0, b: 2.0, c: 3.0}
Necromancer.convert("a:1 b:2.0 c:3").to(:num_hash)    # => {a: 1, b:2.0, c: 3}

String can also be converted to hash with boolean values using

:boolean_hash

:bool_hash

Necromancer.convert("a:yes b:no c:t").to(:bool_hash)  # => {a: true, b: false, c: true}

3.5 Numeric

Necromancer comes ready to convert all the primitive numeric values.

To convert a string to a float do:

Necromancer.convert("1.2a").to(:float)  #  => 1.2

Conversion to numeric in strict mode raises

Necromancer::ConversionTypeError

Necromancer.convert("1.2a").to(:float, strict: true) # => raises error

To convert a string to an integer do:

Necromancer.convert("1a").to(:integer)  #  => 1

However, if you want to convert string to an appropriate matching numeric type do:

Necromancer.convert("1e1").to(:numeric)   # => 10

3.6 Range

Necromancer is no stranger to figuring out ranges from strings. You can pass

,

-

..

...

Necromancer.convert("1,10").to(:range)  # => 1..10

Or to create a range of letters:

Necromancer.convert("a-z").to(:range)   # => "a".."z"

It will handle space characters:

Necromancer.convert("1 . . 10") >> :range   # => 1..10
Necromancer.convert("a . . . z") >> :range  # =>  "a"..."z"

3.7 Custom

In case where provided conversions do not match your needs you can create your own and

register

Object

Proc

3.7.1 Using an Object

Firstly, you need to create a converter that at minimum requires to specify

call

UpcaseConverter = Struct.new(:source, :target) do
  def call(value, options = {})
    value.upcase
  end
end

Inside the

UpcaseConverter

config

Then you need to specify what type conversions this converter will support. For example,

UpcaseConverter

upcase_converter = UpcaseConverter.new(:string, :upcase)

Necromancer provides the

register

converter = Necromancer.new
converter.register(upcase_converter)   # => true if successfully registered

Finally, by invoking

convert

:upcase

converter.convert("magic").to(:upcase)   # => "MAGIC"

3.7.2 Using a Proc

Using a Proc object you can create and immediately register a converter. You need to pass

source

target

convert

converter = Necromancer.new

converter.register do |c|
  c.source= :string
  c.target= :upcase
  c.convert = proc { |value, options| value.upcase }
end

Then by invoking the

convert

:upcase

converter.convert("magic").to(:upcase)   # => "MAGIC"

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/piotrmurach/necromancer. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.

1. Fork it ( https://github.com/piotrmurach/necromancer/fork )
2. Create your feature branch (

   git checkout -b my-new-feature

   )
3. Commit your changes (

   git commit -am 'Add some feature'

   )
4. Push to the branch (

   git push origin my-new-feature

   )
5. Create a new Pull Request

License

The gem is available as open source under the terms of the MIT License.

Copyright

Copyright (c) 2014 Piotr Murach. See LICENSE for further details.