1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
|
;;; stack-core.el --- core functions for stack-mode -*- lexical-binding: t; -*-
;; Copyright (C) 2014 Sean Allred
;; Author: Sean Allred <code@seanallred.com>
;; Keywords: help, hypermedia, mail, news, tools
;; This program is free software; you can redistribute it and/or modify
;; it under the terms of the GNU General Public License as published by
;; the Free Software Foundation, either version 3 of the License, or
;; (at your option) any later version.
;; This program is distributed in the hope that it will be useful,
;; but WITHOUT ANY WARRANTY; without even the implied warranty of
;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
;; GNU General Public License for more details.
;; You should have received a copy of the GNU General Public License
;; along with this program. If not, see <http://www.gnu.org/licenses/>.
;;; Commentary:
;; This file defines basic commands used by all other parts of
;; StackMode. Currently, there are sections that are pretty wildly
;; different from each other (e.g. `Filters' and `Questions'. These
;; will eventually be migrated to their own files with related functions
;; of their ilk -- for now, it is more convenient to keep them handy.
;;; Code:
;;; Requirements
(require 'json)
(require 'url)
;;; Package Logging
(defun stack-message (format-string &rest args)
(message "[stack] %s" (apply #'format format-string args)))
;;; Constants and Customizable Options
(defconst stack-core-api-version
"2.2"
"The current version of the API.")
(defconst stack-core-api-root
(format "http://api.stackexchange.com/%s/" stack-core-api-version)
"The base URL to make requests from.")
(defcustom stack-core-default-keyword-arguments-alist
'(("filters/create" . nil)
(t . ((site . emacs))))
"An alist of keywords to use as the default for a given method.
This collection is in itself an alist; the key is the method and
the value is an alist of the default arguments for this method.
The value for `t' is the default-default... a super-default, if
you will.
See `stack-core-get-default-keyword-arguments' and
`stack-core-build-keyword-arguments'.
")
(defcustom stack-core-cache-requests
t
"Cache requests made to the StackExchange API.")
(defcustom stack-core-unzip-program
"gunzip"
"program used to unzip the response")
(defvar stack-core-remaining-api-requests
nil
"The number of API requests remaining according to the most
recent call. Set by `stack-core-make-request'.")
(defcustom stack-core-remaining-api-requests-message-threshold
50
"After `stack-core-remaining-api-requests' drops below this
number, `stack-core-make-request' will begin printing out the
number of requests left every time it finishes a call.")
;;; Keyword Arguments
(defun stack-core-thing-as-string (thing)
"Return a string representation of THING. If THING is already
a string, just return it."
(cond
((stringp thing) thing)
((symbolp thing) (symbol-name thing))
((numberp thing) (number-to-string thing))))
(defun stack-core-get-default-keyword-arguments (method)
"Gets the correct keyword arguments for METHOD."
(let ((entry
(car
(delq
nil
(mapcar (lambda (pair)
(if (equal method (car pair))
(cdr pair)))
stack-core-default-keyword-arguments-alist)))))
(if entry entry
(cdr (assoc t stack-core-default-keyword-arguments-alist)))))
;;; @todo stack-core-change-default-keyword-arguments
;;; (method new-keyword-arguments)
;;; @todo stack-core-change-default-keyword-arguments-for-key
;;; (method key new-value)
(defun stack-core-build-keyword-arguments (alist)
"Build a \"key=value&key=value&...\"-style string with the elements
of ALIST. If any value in the alist is `nil', that pair will not
be included in the return. If you wish to pass a notion of
false, use the symbol `false'. Each element is processed with
`stack-core-thing-as-string'."
(mapconcat
(lambda (pair)
(concat
(stack-core-thing-as-string (car pair))
"="
(stack-core-thing-as-string (cdr pair))))
(delq nil (mapcar
(lambda (pair)
(when (cdr pair) pair))
alist))
"&"))
;;; Making Requests of StackExchange
(defun stack-core-build-request (method keyword-arguments)
"Build the request string that will be used to process REQUEST
with the given KEYWORD-ARGUMENTS."
(let ((base (concat stack-core-api-root method))
(args (stack-core-build-keyword-arguments keyword-arguments)))
(if (string-equal "" args)
base
(concat base "?" args))))
(defun stack-core-make-request (method &optional keyword-arguments)
"Make a request to the StackExchange API using METHOD and
optional KEYWORD-ARGUMENTS. If no KEYWORD-ARGUMENTS are given,
`stack-core-default-keyword-arguments-alist' is used. Return the
entire response as a complex alist."
(let ((response
(json-read-from-string
(let ((call (stack-core-build-request
method
(cons `(filter . ,stack-core-filter)
(if keyword-arguments keyword-arguments
(stack-core-get-default-keyword-arguments method)))))
(url-automatic-caching stack-core-cache-requests))
;; TODO: url-retrieve-synchronously can return nil if the call is
;; unsuccessful should handle this case
(stack-message "Request: %s" call)
(with-current-buffer (url-retrieve-synchronously call)
(goto-char (point-min))
(if (not (search-forward "\n\n" nil t))
(error "Response corrupted")
(delete-region (point-min) (point))
(buffer-string)))))))
(setq stack-core-remaining-api-requests
(cdr (assoc 'quota_remaining response)))
(when (< stack-core-remaining-api-requests
stack-core-remaining-api-requests-message-threshold)
(stack-message "%d API requests remaining"
stack-core-remaining-api-requests))
response))
(provide 'stack-core)
;;; stack-core.el ends here
;; Local Variables:
;; fill-column: 72
;; End:
|
