# Microformats (ruby)
[](https://travis-ci.org/indieweb/microformats-ruby)
[](https://codeclimate.com/github/indieweb/microformats-ruby)
A Ruby gem to parse HTML containing one or more microformats and [microformats2](http://microformats.org/wiki/microformats-2)
and return a collection of dynamically defined Ruby objects, a Ruby hash or a JSON hash.
## Development Status
Implemented:
* [parsing depth first, doc order](http://microformats.org/wiki/microformats2-parsing#parse_a_document_for_microformats)
* [parsing a p- property](http://microformats.org/wiki/microformats2-parsing#parsing_a_p-_property)
* [parsing a u- property](http://microformats.org/wiki/microformats2-parsing#parsing_a_u-_property)
* [parsing a dt- property](http://microformats.org/wiki/microformats2-parsing#parsing_a_dt-_property)
* [parsing a e- property](http://microformats.org/wiki/microformats2-parsing#parsing_an_e-_property)
* [parsing implied properties](http://microformats.org/wiki/microformats-2-parsing#parsing_for_implied_properties)
* nested properties
* nested microformat with associated property
* dynamic creation of properties
* [rel](http://microformats.org/wiki/rel)
* [normalize u-* property values](http://microformats.org/wiki/microformats2-parsing-faq#normalizing_u-.2A_property_values)
* nested microformat without associated property
* [value-class-pattern](http://microformats.org/wiki/value-class-pattern)
* recognition of [vendor extensions](http://microformats.org/wiki/microformats2#VENDOR_EXTENSIONS)
* backward compatible support for microformats v1
Not Implemented:
* [include-pattern](http://microformats.org/wiki/include-pattern)
## Current Version
4.0.0
## Requirements
* [nokogiri](https://github.com/sparklemotion/nokogiri)
* [json](https://github.com/flori/json)
## Installation
Add this line to your application's Gemfile:
```ruby
gem "microformats"
```
And then execute:
```
bundle
```
Or install it yourself as:
```
gem install microformats
```
## Usage
```ruby
require "microformats"
source = ""
collection = Microformats.parse(source)
# getting a copy of the canonical microformats hash structure
collection.to_hash
# the above, as JSON in a string
collection.to_json
# shortcuts
# return a string if there is only one item found
collection.card.name #=> "Jessica Lynn Suttles"
source = "
Microformats 2
"
collection = Microformats.parse(source)
collection.entry.name.to_s #=> "Microformats 2"
# accessing nested microformats
collection.entry.author.name.to_s #=> "Jessica Lynn Suttles"
# accessing nested microformats can use shortcuts or more expanded method
collection.entry.author.name #=> "Jessica Lynn Suttles"
collection.entry.properties.author.properties.name.to_s #=> "Jessica Lynn Suttles"
# use _ instead of - to get these items
collection.entry.author.first_name #=> "Jessica"
collection.rel_urls #=> {}
source = "
Microformats 2
"
collection = Microformats.parse(source)
# arrays of items with always take the first item by default
collection.entry.author.name #=> "Jessica Lynn Suttles"
collection.entry.author(1).name #=> "Brandon Edens"
# get the actual array with :all
collection.entry.author(:all).count #=> 2
collection.entry.author(:all)[1].name #=> "Brandon Edens"
```
* `source` can be a URL, filepath, or HTML
## Ruby Gem release process
Check out latest code from GitHub repo.
```
git pull origin master
```
Make sure the version has been bumped up in all four places:
- [lib/microformats/version.rb](https://github.com/indieweb/microformats-ruby/blob/master/lib/microformats/version.rb#L2)
- [README.md (three places)](https://github.com/indieweb/microformats-ruby/blob/master/README.md)
Do a test build locally to make sure it builds properly.
```
rake build
```
If that works, then do a test install locally.
```
rake install
```
If that works, uninstall the gem.
```
gem uninstall microformats
```
Clean up any mess made from testing.
```
rake clean
rake clobber
```
Assuming your one of the gem owners and have release privileges, release the gem!
```
rake release
```
If that works, you’ve just release a new version of the gem! Yay! You can see it at:
[https://rubygems.org/gems/microformats](https://rubygems.org/gems/microformats)
If `rake release` failed because of an error with your authentication to rubygems.org, follow their instructions in the error message. Then repeat the `rake release` step.
If any other errors failed along the way before `rake release`, try to figure them out or reach out to the IRC/Slack channel for help.
Good luck.
## Authors
- Ben Roberts / [@dissolve](https://github.com/dissolve)
- Jessica Lynn Suttles / [@jlsuttles](https://github.com/jlsuttles)
- Shane Becker / [@veganstraightedge](https://github.com/veganstraightedge)
- Chris Stringer / [@jcstringer](https://github.com/jcstringer)
- Michael Mitchell / [@variousred](https://github.com/variousred)
- Jessica Dillon / [@jessicard](https://github.com/jessicard)
- Jeena Paradies / [@jeena](https://github.com/jeena)
- Marty McGuire / [@martymcguire](https://github.com/martymcguire)
## Contributions
1. Fork it
2. Get it running (see Installation above)
3. Create your feature branch (`git checkout -b my-new-feature`)
4. Write your code and **specs**
5. Commit your changes (`git commit -am 'Add some feature'`)
6. Push to the branch (`git push origin my-new-feature`)
7. Create new Pull Request
If you find bugs, have feature requests or questions, please
[file an issue](https://github.com/indieweb/microformats-ruby/issues).
## Testing
### Specs
This uses a copy of [microformats tests repo](https://github.com/microformats/tests).
To run specs
```
rake spec
```
###Interactive
You can use the code interacively for testing but running
```
bundle console
```
## License
Microformats (ruby) is dedicated to the public domain using Creative Commons -- CC0 1.0 Universal.
http://creativecommons.org/publicdomain/zero/1.0