Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 180 lines (119 sloc) 5.673 kb
e8d3366 darcs repo pull
alfons haffmans authored
1 # CL-TWITTER
2
3 ## NOTE
4
5 #### 2010-10-24
6
7 This is a clone of cl-twitter's darcs repository http://www.common-lisp.net/project/cl-twitter/darcs/cl-twitter.
8 More information can be found [on cl-twitters cliki page](http://common-lisp.net/project/cl-twitter/).
9
6225157 compiles but is crippled
alfons haffmans authored
10 This version compiles. Authentication does not work. Features which relay on that part obviously will not work.
11 The search interface does work, but you're obviously going to be severly rate limited.
12
e8d3366 darcs repo pull
alfons haffmans authored
13
14
15 ## Description
16
17 This is a simple interface to the Twitter API current as of February 2009:
18 (Reference: http://apiwiki.twitter.com/REST+API+Documentation)
19
20 It also implements the search and trends APIs.
21 (Reference: http://apiwiki.twitter.com/Search+API+Documentation)
22
23 The primary interface to the API is via the twitter-op command:
24 (twitter-op :command &rest args)
25 which calls the API :command and returns one or more 'elements' which
26 can be primitives, 'twitter-user, 'tweet or 'twitter-message. This
27 API uses struct objects for composite values such as users or tweets.
28
29 You can view documentation for commands and elements using:
30 (list-commands)
31 (command-help :command-name)
32 (element-help 'type)
33 types: twitter-user, tweet, twitter-message, search-result, search-ref
34
35 Loading: :
36
37 (asdf:oos 'asdf:load-op :cl-twitter) -> Creates package :twitter and :twit
38 (asdf:oos 'asdf:load-op :cl-twitter-db) -> Uses elephant to record elements
39
40 ## Authentication:
41
42
43 Most API commands require an authenticating user "An authenticating"
44 user (with valid username & password slots) can be passed to a command
45 using the :user option. There is a convenience function
46 authenticate-user which takes a username and password, creates and
47 populates a user object (if authentication works) and sets a global
48 variable *twitter-user* which will be used to authenticate calls by
49 default. The :user option overrides the default parameter.
50
51 ## Quick Start and Shortcuts:
52
53
54 There are a small set of quick interactive routines for using the API:
55
56 (authenticate-user screen-name password) - will set the default user if valid
57 (send-tweet text) - will post a tweet / status update for the current user
58 (latest-tweets) - the list of latest tweets for each user
59 (print-tweets list) - will print the tweet sender & text
60
61 ## Example use:
62
63
7528efe cleanup
alfons haffmans authored
64 TWITTER> (twitter-op :test)
65 "ok"
e8d3366 darcs repo pull
alfons haffmans authored
66
7528efe cleanup
alfons haffmans authored
67 TWITTER> (authenticate-user "ieslick" "password")
68 #<TWITTER-USER 'ieslick'>
e8d3366 darcs repo pull
alfons haffmans authored
69
7528efe cleanup
alfons haffmans authored
70 TWITTER> (latest-tweets)
71 (#<TWEET 'ieslick' id:1219635898> #<TWEET 'ieslick' id:1217269236>
72 #<TWEET 'ieslick' id:1215984895> #<TWEET 'ieslick' id:1214353382>)
e8d3366 darcs repo pull
alfons haffmans authored
73
7528efe cleanup
alfons haffmans authored
74 TWITTER> (print-tweets *)
75 status: "The lisp twitter api is nearly done!"
76 by: Ian Eslick (ieslick) on: Tue Feb 17 00:49:11 +0000 2009
e8d3366 darcs repo pull
alfons haffmans authored
77
7528efe cleanup
alfons haffmans authored
78 status: "Benefits of working from home; lunchtime stew in Cambridge, MA http://l\
79 oopt.us/-Hps2Q"
80 by: Ian Eslick (ieslick) on: Mon Feb 16 17:49:52 +0000 2009
e8d3366 darcs repo pull
alfons haffmans authored
81
7528efe cleanup
alfons haffmans authored
82 status: "My lisp can tweet!"
83 by: Ian Eslick (ieslick) on: Mon Feb 16 04:52:28 +0000 2009
e8d3366 darcs repo pull
alfons haffmans authored
84
7528efe cleanup
alfons haffmans authored
85 status: "Family outing! in Cambridge, MA http://loopt.us/zUhMpQ"
86 by: Ian Eslick (ieslick) on: Sun Feb 15 21:14:26 +0000 2009
e8d3366 darcs repo pull
alfons haffmans authored
87
7528efe cleanup
alfons haffmans authored
88 NIL
e8d3366 darcs repo pull
alfons haffmans authored
89
7528efe cleanup
alfons haffmans authored
90 TWITTER> (send-tweet "cl-twitter is released!")
91 #<TWEET 'ieslick' id:1219635898>
e8d3366 darcs repo pull
alfons haffmans authored
92
7528efe cleanup
alfons haffmans authored
93 TWITTER> (describe *)
94 by: ieslick (Ian Eslick ) created: Tue Feb 17 17:33:33 +0000 2009
95 msg: cl-twitter is released!
96 ; No value
e8d3366 darcs repo pull
alfons haffmans authored
97
7528efe cleanup
alfons haffmans authored
98 TWITTER> (twitter-op :user-show)
e8d3366 darcs repo pull
alfons haffmans authored
99
100
101 ## Search API:
102
103
104 The search API returns a 'search-result element which contains a set
105 of 'search-ref elements accessible via (search-result-results elt)
106
107 (twitter-search "query string" &rest args) - is a shortcut for
108 (twitter-op :search :q "query string" &rest args)
109 and returns two values: the list of refs and the 'search-result elt.
110
111 (twitter-trends) - returns the top 20 twitter search trends
112
113
114 ## Twitter Database
115
116
117 Simple elephant-based database for users, tweet and messages. When
118 the db is open, it automatically stores objects that are retrieved via
119 the API and provides a series of simple accessors that can be easily
120 expanded.
121
122 Open and close:
123 (open-twitter-db &optional elephant-spec)
124 (close-twitter-db)
125
126 Users
127 (find-twitter-user &key id screen-name name)
128 (map-twitter-users fn)
129
130 Tweets
131 (get-tweet id)
132 (map-tweets fn)
133 (map-user-tweets fn user)
134 (user-tweets user)
135
136 Messages
137 (get-tweet-msg id)
138 (map-tweet-msgs fn)
139 (map-user-msgs fn user)
140 (user-msgs user)
141 (map-user-received-messages fn user)
142
143
144 ## Error Handling:
145
146
147 Any API call errors throw a twitter-api-condition which provides
148 the return code and short and long code messages. It also provides
149 the failing URI and the specific server message. The accessors are
150 not exported to avoid conflicts, but the slotnames are:
151 return-code, short, long, request, uri.
152
153 You can play with this, for example, by trying to perform an API
154 command with invalid user authentication.
155
156 ## API Status:
157
158
159 This interface was interactively tested, but bugs remain and not all
160 features have been exercised. Help tracking down the last of the
161 bugs is always appreciated!
162
163 I have also not completely documented all the element slots. This
164 should be easy to fix and you can also refer to the twitter APIs.
165
166 ## DB API Status:
167
168
169 The DB interface is highly experimental and has only been partially
170 tested. In particular, we currently store copies of embedded
171 structures and should use the existing DB id references to save/restore.
172 We should also hook into the lookup functions in the main API to avoid
173 reparsing stored objects.
174
175 The time index is currently based on strings, so not properly ordered,
176 we need to cleanup using universal time integers instead of strings
177 throughout the API.
178
179 Ian Eslick
180 2/26/2009
Something went wrong with that request. Please try again.