Merge pull request #1 from liron-navon/liron-navon/improving-document…

…ation

added idea (goland) to gitignore and updated documentation ChimeraCoder#242

.gitignore

@@ -3,4 +3,5 @@
 *.swn
 conf.sh
 *.patch
+.idea/
 anaconda.test

README

@@ -1,28 +1,41 @@
 Anaconda
 ========
 
+
 [![Build Status](https://travis-ci.org/ChimeraCoder/anaconda.svg?branch=master)](https://travis-ci.org/ChimeraCoder/anaconda) [![Build Status](https://ci.appveyor.com/api/projects/status/63pi6csod8bps80i/branch/master?svg=true)](https://ci.appveyor.com/project/ChimeraCoder/anaconda/branch/master) [![GoDoc](https://godoc.org/github.com/ChimeraCoder/anaconda?status.svg)](https://godoc.org/github.com/ChimeraCoder/anaconda)
 
+
 Anaconda is a simple, transparent Go package for accessing version 1.1 of the Twitter API.
 
+
 Successful API queries return native Go structs that can be used immediately, with no need for type assertions.
 
 
+For more information and a complete api please see the [GoDoc.](https://godoc.org/github.com/ChimeraCoder/anaconda)
+
+
 
 Examples
 --------
 
+
 ### Authentication
 
+
 If you already have the access token (and secret) for your user (Twitter provides this for your own account on the developer portal), creating the client is simple:
 
+
 ```go
-api := anaconda.NewTwitterApiWithCredentials("your-access-token", "your-access-token-secret", "your-consumer-key", "your-consumer-secret")
+api := anaconda.NewTwitterApiWithCredentials("user-token", "user-token-secret", "your-consumer-key", "your-consumer-secret")
 ```
 
+
 ### Queries
+Almost all of anaconda's methods require the Values struct from the ["net/url" package](https://golang.org/pkg/net/url/)
+
+
+Queries are methods of an authenticated `TwitterApi` struct. In v1.1 of Twitter's API, all requests should be authenticated.
 
-Queries are conducted using a pointer to an authenticated `TwitterApi` struct. In v1.1 of Twitter's API, all requests should be authenticated.
 
 ```go
 searchResult, _ := api.GetSearch("golang", nil)
@@ -32,109 +45,187 @@ for _ , tweet := range searchResult.Statuses {
 ```
 Certain endpoints allow separate optional parameter; if desired, these can be passed as the final parameter.
 
+
 ```go
 //Perhaps we want 30 values instead of the default 15
 v := url.Values{}
 v.Set("count", "30")
 result, err := api.GetSearch("golang", v)
 ```
 
+
 (Remember that `url.Values` is equivalent to a `map[string][]string`, if you find that more convenient notation when specifying values). Otherwise, `nil` suffices.
 
+
 ### Streaming
 
+
 Anaconda supports the Streaming APIs. You can use `PublicStream*` or `UserStream` API methods.
-A go loop is started an gives you an stream that sends `interface{}` objects through it's `chan` `C`
+A go loop is started and gives you a stream that sends `interface{}` objects through it's `chan` `C`
 Objects which you can cast into a tweet, event and more.
 
 
+Some services like [FireHose](https://developer.twitter.com/en/docs/tweets/compliance/api-reference/compliance-firehose) and [Decahose](https://developer.twitter.com/en/docs/tweets/sample-realtime/overview/decahose) require enterprise access to the twitter api.
+
+
+Example for the PublicStreamFilter ([statuses/filter](https://developer.twitter.com/en/docs/tweets/filter-realtime/overview))
 ````go
-v := url.Values{}
-s := api.UserStream(v)
-
-for t := range s.C {
-  switch v := t.(type) {
-  case anaconda.Tweet:
-    fmt.Printf("%-15s: %s\n", v.User.ScreenName, v.Text)
-  case anaconda.EventTweet:
-    switch v.Event.Event {
-    case "favorite":
-      sn := v.Source.ScreenName
-      tw := v.TargetObject.Text
-      fmt.Printf("Favorited by %-15s: %s\n", sn, tw)
-    case "unfavorite":
-      sn := v.Source.ScreenName
-      tw := v.TargetObject.Text
-      fmt.Printf("UnFavorited by %-15s: %s\n", sn, tw)
-    }
-  }
+values := url.Values{} 
+values.Set("track", "#golang,#go,#anaconda,#ChimeraCoder,#fakenews,#twitter-dev")
+stream := api.UserStream(values)
+counter := 0
+
+for data := range s.C {
+	tweet, ok := data.(anaconda.Tweet)
+	if ok {
+	    fmt.Println(tweet.Text)
+	    counter += 1
+		if(counter == 50) {
+		    // close the channel and release resources of this stream
+		    api.Close()
+		}
+	}
+}
+````
+
+
+Example for the UserStream
+````go
+values := url.Values{}
+stream := api.UserStream(values)
+
+
+for data := range stream.C {
+	switch tweet := data.(type) {
+	case anaconda.Tweet:
+		fmt.Printf("%-15s: %s\n", tweet.User.ScreenName, tweet.Text)
+	case anaconda.EventTweet:
+		switch tweet.Event.Event {
+		case "favorite":
+			screenName := tweet.Source.ScreenName
+			text := tweet.TargetObject.Text
+			fmt.Printf("Favorited by %-15s: %s\n", screenName, text)
+		case "unfavorite":
+			screenName := tweet.Source.ScreenName
+			text := tweet.TargetObject.Text
+			fmt.Printf("UnFavorited by %-15s: %s\n", screenName, text)
+		}
+	}
 }
 ````
 
 
+For more information about streaming and streaming parameter please view the [Standard streaming API request parameters](https://developer.twitter.com/en/docs/tweets/filter-realtime/guides/basic-stream-parameters)
+
+
+
 
 Endpoints
 ---------
 
+
 Anaconda implements most of the endpoints defined in the [Twitter API documentation](https://developer.twitter.com/en/docs). For clarity, in most cases, the function name is simply the name of the HTTP method and the endpoint (e.g., the endpoint `GET /friendships/incoming` is provided by the function `GetFriendshipsIncoming`).
 
-In a few cases, a shortened form has been chosen to make life easier (for example, retweeting is simply the function `Retweet`)
+
+In a few cases, a shortened form has been chosen to make life easier (for example, retweeting is simply the function `Retweet`).
+
 
 
 
 Error Handling, Rate Limiting, and Throttling
 ---------------------------------------------
 
+
 ### Error Handling
 
+
 Twitter errors are returned as an `ApiError`, which satisfies the `error` interface and can be treated as a vanilla `error`. However, it also contains the additional information returned by the Twitter API that may be useful in deciding how to proceed after encountering an error.
 
 
+
+
 If you make queries too quickly, you may bump against Twitter's [rate limits](https://developer.twitter.com/en/docs/basics/rate-limits). If this happens, `anaconda` automatically retries the query when the rate limit resets, using the `X-Rate-Limit-Reset` header that Twitter provides to determine how long to wait.
 
+
 In other words, users of the `anaconda` library should not need to handle rate limiting errors themselves; this is handled seamlessly behind-the-scenes. If an error is returned by a function, another form of error must have occurred (which can be checked by using the fields provided by the `ApiError` struct).
 
 
-(If desired, this feature can be turned off by calling `ReturnRateLimitError(true)`.)
+
+
+(If desired, this feature can be turned off by calling `api.ReturnRateLimitError(true)`.)
+
+
 
 
 ### Throttling
 
+
 Anaconda now supports automatic client-side throttling of queries to avoid hitting the Twitter rate-limit.
 
+
 This is currently *off* by default; however, it may be turned on by default in future versions of the library, as the implementation is improved.
 
 
+
+
 To set a delay between queries, use the `SetDelay` method:
 
+
 ```go
 api.SetDelay(10 * time.Second)
 ```
 
+
 Delays are set specific to each `TwitterApi` struct, so queries that use different users' access credentials are completely independent.
 
 
+
+
 To turn off automatic throttling, set the delay to `0`:
 
+
 ```go
 api.SetDelay(0 * time.Second)
 ```
 
+
 ### Query Queue Persistence
 
-If your code creates a NewTwitterApi in a regularly called function, you'll need to call `.Close()` on the API struct to clear the queryQueue and allow the goroutine to exit. Otherwise you could see goroutine and therefor heap memory leaks in long-running applications.
+
+If your code creates a NewTwitterApi in a regularly called function, you'll need to call `.Close()` on the API struct to clear the queryQueue and allow the goroutine to exit. Otherwise, you could see goroutine and therefor heap memory leaks in long-running applications.
+
 
 ### Google App Engine
 
+
 Since Google App Engine doesn't make the standard `http.Transport` available, it's necessary to tell Anaconda to use a different client context.
 
+
 ```go
 api = anaconda.NewTwitterApi("", "")
 c := appengine.NewContext(r)
 api.HttpClient.Transport = &urlfetch.Transport{Context: c}
 ```
 
 
+### Twitter Media api
+
+Anaconda support the media api, currently file uploads to the new media api ([media/upload](https://developer.twitter.com/en/docs/media/upload-media/api-reference/post-media-upload)) is available only in base64.
+
+```go
+// this is a one pixel png image from: http://png-pixel.com/
+myBase64Image := "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg=="
+
+media, err := api.UploadMedia(myBase64Image)
+if(err == nil){
+    // use this string id when referencing twitter media
+    fmt.Println(media.MediaIDString)
+}
+```
+
+Video uploads can be made using the media api by calling UploadMedia, or by using the ``UploadVideoInit``, ``UploadVideoAppend`` and ``UploadVideoFinalize`` methods.
+
+
 License
 -------
 Anaconda is free software licensed under the MIT/X11 license. Details provided in the LICENSE file.