Browse Source

Fill out README.md.

Douglas Thrift 10 years ago
parent
commit
6c823b386c
1 changed files with 62 additions and 2 deletions
  1. 62 2
      README.md

+ 62 - 2
README.md

@@ -1,6 +1,13 @@
 # MachineTag
 
-TODO: Write a gem description
+[![Gem Version](https://badge.fury.io/rb/machine_tag.png)](http://badge.fury.io/rb/machine_tag)
+[![Build Status](https://travis-ci.org/douglaswth/machine_tag.png?branch=master)](https://travis-ci.org/douglaswth/machine_tag)
+[![Dependency Status](https://gemnasium.com/douglaswth/machine_tag.png)](https://gemnasium.com/douglaswth/machine_tag)
+
+MachineTag is a Ruby library for using machine tags like those used on [Flickr] and [RightScale].
+
+[Flickr]: http://www.flickr.com/help/tags/#613430
+[RightScale]: http://support.rightscale.com/12-Guides/RightScale_101/06-Advanced_Concepts/Tagging
 
 ## Installation
 
@@ -18,7 +25,60 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+MachineTag provides two classes for dealing with machine tags and tags in general: `MachineTag::Tag`
+and `MachineTag::Set`:
+
+### MachineTag::Tag
+
+The MachineTag::Tag class represents a tag which can either be a machine tag or a plain tag. It 
+inherits from [String] so it can be used in the same ways.
+
+[String]: http://ruby-doc.org/core-1.9.3/String.html
+
+```ruby
+plain_tag = MachineTag::Tag.new('geotagged')
+
+plain_tag == 'geotagged'    # => true
+plain_tag.machine_tag?      # => false
+
+machine_tag = MachineTag::Tag.new('geo:lat=34.4348067')
+
+machine_tag == 'geo:lat=34.4348067'     # => true
+machine_tag.machine_tag?                # => true
+machine_tag.namespace                   # => "geo"
+machine_tag.predicate                   # => "lat"
+machine_tag.namespace_and_predicate     # => "geo:lat"
+machine_tag.value.to_f                  # => 34.4348067
+
+machine_tag = MachineTag::Tag.machine_tag('geo', 'lon', -119.8016962)
+
+machine_tag == 'geo:lon=-119.8016962'   # => true
+machine_tag.machine_tag?                # => true
+```
+
+### MachineTag::Set
+
+The `MachineTag::Set` class represents a set of tags and provides a way of looking them up by
+namespace or by namespace and predicate. It inherits from the [Set] so it can be used in the same
+ways. If `String` objects are passed into it they will automatically be converted to
+`MachineTag::Tag` objects.
+
+[Set]: http://ruby-doc.org/stdlib-1.9.3/libdoc/set/rdoc/Set.html
+
+```ruby
+tags = MachineTag::Set['geotagged', 'geo:lat=34.4348067', 'geo:lon=-119.8016962']
+
+tags.include?('geotagged')  # => true
+tags.plain_tags             # => #<Set: {"geotagged"}>
+tags.machine_tags           # => #<Set: {"geo:lat=34.4348067", "geo:lon=-119.8016962"}>
+tags['geo']                 # => #<Set: {"geo:lat=34.4348067", "geo:lon=-119.8016962"}>
+tags['geo:lat']             # => #<Set: {"geo:lat=34.4348067"}>
+tags['geo', 'lon']          # => #<Set: {"geo:lon=-119.8016962"}>
+```
+
+More information can be found in the [documentation].
+
+[documentation]: http://rubydoc.info/gems/machine_tag/frame
 
 ## Contributing