<commit_before># SirenClient [![Build Status](https://travis-ci.org/cha55son/siren_client.svg)](https://travis-ci.org/cha55son/siren_client)

A simple client for traversing Siren APIs. Not sure what Siren is? View the spec here: https://github.com/kevinswiber/siren.

## Usage

Grabbing the root of the API.

```ruby
require 'siren_client'

# The simplest form
root = SirenClient.get('http://siren-api.example.com')

# Advanced usage
root = SirenClient.get('http://siren-api.example.com', {
  headers: { "Accept": "application/json", ... },
  basic_auth: { username: 'person', password: '<PASSWORD>' },
  timeout: 5,
  ... # Refer to https://github.com/jnunemaker/httparty/blob/master/lib/httparty.rb#L45
      # For more options.
})
```

There are four main parts to an [Entity](https://github.com/kevinswiber/siren#entity) in Siren. (properties, entities, links, and actions) To make your life a little easier SirenClient will try to pick one of the four items given a method name. Otherwise you can access the data directly.

### Properties

```ruby
# If color was a property on the root you could do something like this:
root.color 
# or 
root.properties['color']
```

### Entities

Since entities are usually the most important, SirenClient provides enumerable support to obtain them.

```ruby
# Will grab the entity as if root was an array.
root[x] 
# or
root.entities[x] # This is an array
# Will iterate through all the entities on the root.
root.each do |entity|
  # do something
end
```

#### Entity sub-links

If the root contains an entity that is an [embedded link](https://github.com/kevinswiber/siren#embedded-link) you can call it based on it's class name. This will also execute the link's href and return you the entity.

```ruby
root.embedded_link_class_name
root.messages # For example
```

### Links

```ruby
# If you know the link's name you could do something like this:
root.concepts
# or
root.links['concepts'].go
```

### Actions

```ruby<commit_msg>Updated to document enumerable support and searching.<commit_after># SirenClient [![Build Status](https://travis-ci.org/cha55son/siren_client.svg)](https://travis-ci.org/cha55son/siren_client)

A simple client for traversing Siren APIs. Not sure what Siren is? View the spec here: https://github.com/kevinswiber/siren.

## Usage

Grabbing the root of the API.

```ruby
require 'siren_client'

# The simplest form
root = SirenClient.get('http://siren-api.example.com')

# Advanced usage
root = SirenClient.get('http://siren-api.example.com', {
  headers: { "Accept": "application/json", ... },
  basic_auth: { username: 'person', password: '<PASSWORD>' },
  timeout: 5,
  ... # Refer to https://github.com/jnunemaker/httparty/blob/master/lib/httparty.rb#L45
      # For more options.
})
```

There are four main parts to an [Entity](https://github.com/kevinswiber/siren#entity) in Siren. (properties, entities, links, and actions) To make your life a little easier SirenClient will try to pick one of the four items given a method name. Otherwise you can access the data directly.

### Properties

```ruby
# If color was a property on the root you could do something like this:
root.color 
# or 
root.properties['color']
```

### Entities

Since entities are usually the most important, SirenClient provides enumerable support to obtain them.

```ruby
# Will grab the entity as if root was an array.
root[x] 
# or
root.entities[x] # This is an array
# Will iterate through all the entities on the root.
root.each do |entity|
  # do something
end
# With full enumerable support entities work similarly to arrays
root.map { |entity| ... }
root.select { |entity| ... }
root.find { |entity| ... }
# You can view all the enumerable methods here: http://ruby-doc.org/core-2.0.0/Enumerable.html
```

Entities also provide the method `.search` for searching across sub-entities' classes, rels, and hrefs (sub-links only).

```ruby
root.search("messages") # => Array<SirenClient::Entity>
root.search(/(messages|concepts)/) # => Array<SirenClient::Entity>
```

#### Entity sub-links

If the root contains an entity that is an [embedded link](https://github.com/kevinswiber/siren#embedded-link) you can call it based on it's class name. This will also execute the link's href and return you the entity.

```ruby
root.embedded_link_class_name
root.messages # For example
```

### Links

```ruby
# If you know the link's name you could do something like this:
root.concepts
# or
root.links['concepts'].go
```

### Actions

```ruby
{'fraction_non_alphanumeric': 0.12711487088156723, 'fraction_numerical': 0.003784505788067676, 'mean_word_length': 4.2672919109026966, 'pattern_counts': {'":': 2, '<': 7, '<?xml version=': 0, '>': 9, 'https://': 12, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6284380', 'n_tokens_mistral': 1487, 'n_tokens_neox': 1379, 'n_words': 498}