# fife

**Repository Path**: aetherus/fife

## Basic Information

- **Project Name**: fife
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2015-11-23
- **Last Updated**: 2020-12-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Fife

**Fife** is a multiple IO pipelining tool, originally designed for
file uploading through HTTP, but can be used in any other cases.

## Warning
This gem is in early development stage, and the interface could be changed enormously in future releases.

## Installation

Add this line to your application's Gemfile:

```ruby
gem 'fife'
```

And then execute:

    $ bundle

Or install it yourself as:

    $ gem install fife

## Usage

Create a `Fife` instance by calling `Fife(io_ary)`,
then chain as many `pipe` calls as you want.

```ruby
io_ary = [
  File.new('/path/to/my/file'),
  StringIO.new('Hello world'),
  Tempfile.new('temp')
]

Fife(io_ary).pipe(-> io {io})
            .pipe(-> io {[io, io]})
            .pipe(:close)
```

### Kernel#Fife(*ios)

This method returns a `Fife::Pipe` instance for chaining.

This method expect 0 or more IO-like objects as arguments.
Alternatively it can take an array of IO-like objects

### Fife::Pipe#pipe

This method returns a new `Fife::Pipe` instance.

It has 2 forms of usage:

1.  pass an operation as the argument
`Fife(io_ary).pipe(->io{io})`
2.  pass the underscored name of an operation class,
and 0 or more arguments as the constructor arguments of that class.
`Fife(io_ary).pipe(:store, my_storage)`
see *Define custom operations* for detail.

### Operation

An operation is an object that responds to `call(io)`, and returns 0 or more IO-like objects.
A *lambda* is often used as an operation, but an operation can be of any type.

Currently, `Fife` ships with 4 operations: `:noop`, `:name`, `:store` and `:close`

* noop
Performs no operation on the IO, and returns the IO directly.
* close
Closes the IO if not already closed.
* store
Stores the content of the IO.
* name
Gives the IO a name according to the per-io naming strategy you specified.
You can retrieve it's name by calling `#name` on the IO instance.
```ruby
name = Fife::Operations::Name.new(->io { 'some_name' })
Fife(io_ary).pipe(name)

# Or
Fife(io_ary).pipe(:name, ->io { 'some_name' })
```

#### Define custom operations

If you feel lambdas are not enough for your job,
you can easily define your own operations.

```ruby
class MyOperation
  def initialize(arg1, arg2)
    # Initialize the Operation
  end

  def call(io)
    # Handle the io and return some IO instances
  end
end

# Register it
Fife::Operations.register(:my_op, MyOperation)
```

Then you can use it like

```ruby
Fife(io_ary).pipe(:my_op, 1, 2)
```

### Storage
To leverage the `:store` operation, you need a *storage*.

A storage is just an object that responds to `store(io)`.

Currently, **Fife** ships with 2 storage classes:

* `Fife::Storage::Null`
Simply does nothing
* `Fife::Storage::Sftp`
Streams the IO to a remote file via SFTP.
This storage should be used with `:name` operation because
the remote filename depends on the name of the IO.
(I know it's nasty, but it's still under developing)

```ruby
storage = Fife::Storage::Sftp.new do
  host 'localhost'
  user 'me'
  remote_dir '/path/to/my/remote/dir'
  naming -> io {"lorem_ipsum_#{rand}"}
  ssh_options password: 's3cret'
end
Fife(io_ary).pipe(:store, storage)
```

### Abort on fail
By default, **Fife** ignores all failures and keeps on executing further operations on succeeded operations.  
This behavior can be changed by passing `abort_on_fail: true` to `Kernel#Fife`:

```ruby
Fife(io_ary, abort_on_fail: true)
```

When `abort_on_fail` is turned on, if some operation raises error, no further operation will be executed,
and an `Fife::Pipe::Aborted` will be raised.
You can get the real causes by accessing `Fife::Pipe::Aborted#causes`

## Development

After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake false` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).

## Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/aetherus/fife.