Permalink
Browse files

Add a README.

  • Loading branch information...
1 parent 5fdb85f commit 61a57b80f8dda29fed6841fe8d87d4c3901807bc @fcuny committed Aug 14, 2016
Showing with 106 additions and 1 deletion.
  1. +106 −1 README.md
View
107 README.md
@@ -1,5 +1,110 @@
+# NAME
+
Net::HTTP::Spore - SPORE client
[![Build Status](https://travis-ci.org/franckcuny/net-http-spore.svg?branch=master)](https://travis-ci.org/franckcuny/net-http-spore)
-Documentation is available on [CPAN](https://metacpan.org/pod/Net::HTTP::Spore).
+# VERSION
+
+version 0.07
+
+# SYNOPSIS
+
+ my $client = Net::HTTP::Spore->new_from_spec('twitter.json');
+
+ # from JSON specification string
+ my $client = Net::HTTP::Spore->new_from_string($json);
+
+ # for identica
+ my $client = Net::HTTP::Spore->new_from_spec('twitter.json', base_url => 'http://identi.ca/com/api');
+
+ $client->enable('Format::JSON');
+
+ my $timeline = $client->public_timeline(format => 'json');
+ my $tweets = $timeline->body;
+
+ foreach my $tweet (@$tweets) {
+ print $tweet->{user}->{screen_name}. " says ".$tweet->{text}."\n";
+ }
+
+ my $friends_timeline = $client->friends_timeline(format => 'json');
+
+# DESCRIPTION
+
+This module is an implementation of the SPORE specification.
+
+To use this client, you need to use or to write a SPORE specification of an
+API. A description of the SPORE specification format is available at
+[http://github.com/SPORE/specifications/blob/master/spore\_description.pod](http://github.com/SPORE/specifications/blob/master/spore_description.pod)
+
+Some specifications for well-known services are available
+[http://github.com/SPORE/api-description](http://github.com/SPORE/api-description).
+
+## CLIENT CREATION
+
+First you need to create a client. This can be done using two methods,
+**new\_from\_spec** and **new\_from\_string**. The client will read the specification
+file to create the appropriate methods to interact with the API.
+
+## MIDDLEWARES
+
+It's possible to activate some middlewares to extend the usage of the client.
+If you're using an API that discuss in JSON, you can enable the middleware
+[Net::HTTP::Spore::Middleware::JSON](https://metacpan.org/pod/Net::HTTP::Spore::Middleware::JSON).
+
+ $client->enable('Format::JSON');
+
+or only on some path
+
+ $client->enable_if(sub{$_->[0]->path =~ m!/path/to/json/stuff!}, 'Format::JSON');
+
+For very simple middlewares, you can simply pass in an anonymous function
+
+ $client->enable( sub { my $request = shift; ... } );
+
+## METHODS
+
+- new\_from\_spec($specification\_file, %args)
+
+ Create and return a [Net::HTTP::Spore::Core](https://metacpan.org/pod/Net::HTTP::Spore::Core) object, with methods generated
+ from the specification file. The specification file can either be a file on
+ disk or a remote URL.
+
+- new\_from\_string($specification\_string, %args)
+
+ Create and return a [Net::HTTP::Spore::Core](https://metacpan.org/pod/Net::HTTP::Spore::Core) object, with methods
+ generated from a JSON specification string.
+
+## TRACING
+
+[Net::HTTP::Spore](https://metacpan.org/pod/Net::HTTP::Spore) provides a way to trace what's going on when doing a
+request.
+
+### Enabling Trace
+
+You can enable tracing using the environment variable **SPORE\_TRACE**. You can
+also enable tracing at construct time by adding **trace => 1** when calling
+**new\_from\_spec**.
+
+### Trace Output
+
+By default output will be directed to **STDERR**. You can specify another
+default output:
+
+ SPORE_TRACE=1=log.txt
+
+or
+
+ ->new_from_spec('spec.json', trace => '1=log.txt');
+
+# AUTHORS
+
+- franck cuny <franck@lumberjaph.net>
+- Ash Berlin <ash@cpan.org>
+
+# COPYRIGHT AND LICENSE
+
+This software is copyright (c) 2012 by linkfluence.
+
+This is free software; you can redistribute it and/or modify it under
+the same terms as the Perl 5 programming language system itself.

0 comments on commit 61a57b8

Please sign in to comment.