summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorSergeyMironov <>2017-06-29 09:48:00 (GMT)
committerhdiff <hdiff@hdiff.luite.com>2017-06-29 09:48:00 (GMT)
commit84af287100b61dc468f102ec3ec1a3eeec1ae34b (patch)
tree164427bd7f680efffafaff7337844a86a912e5d4
parent8406389cdd7af068ef92281cae91cd0d68e76acd (diff)
version 1.8.41.8.4
-rw-r--r--README.md82
-rw-r--r--VKHS.cabal2
-rw-r--r--src/Web/VKHS.hs24
-rw-r--r--src/Web/VKHS/API/Base.hs4
4 files changed, 58 insertions, 54 deletions
diff --git a/README.md b/README.md
index 3979b13..fab4440 100644
--- a/README.md
+++ b/README.md
@@ -2,31 +2,33 @@ VKHS
====
VKHS provides access to [Vkontakte](http://vk.com) social network, popular
-mainly in Russia. Library can be used to login into the network as a standalone
-application (OAuth implicit flow as they call it). Having the access token, it
-is possible to call various API methods to query audio files or retrieve wall
-messages. For now, vkhs offers limited error detection and no captcha support.
+mainly in Russia. Library can be used to login into the network as a
+standalone application (OAuth implicit flow as they call it). Having the access
+token, it is possible to call various API methods to -query audio files-
+(disabled by VK) or retrieve wall messages.
Features
========
-* Provide access to VK API. Interface options include: VK monad and `vkq` command
+* Provides access to VK API. Interface options include: VK monad and `vkq` command
line tool.
-* Use HTTPS protocol.
-* Solve login form interaction, may be used to operate new/disposable VK accounts.
-* VK monad is an interruptable coroutine. The superwiser supports ondemand
- re-login, and may be used for long-running tasks.
+* Uses HTTPS protocol.
+* Solves login form interaction, may be used to operate new/disposable VK accounts.
+* VK monad is designed as an interruptable coroutine. The supervisor supports
+ ondemand re-login, and may be used for long-running tasks.
* Project includes a set of `Web.VKHS.API.Simple` wrappers designed to be
copied into `runhaskell` scripts and tweaked according to ones need.
+* No more dependencies on curlhs/taglib.
Issues
======
-* Still no support for captchas, one probably should hack `defaultSuperwiser`
- and add them
-* Network connection timeout is not handled by superwiser
+* Still no support for captchas, one probably should hack `defaultSupervisor`
+ and add them.
+* Network connection timeout is not handled by the coroutine supervisor.
* Minor issues here and there. Use `git grep FIXME` to find them
-* File uploading still not functioning
+* File uploading still not functioning.
+* Lots grammatical mistakes. Any corrections will be kindly accepted.
Installing
==========
@@ -39,9 +41,6 @@ In order to install VKHS, one typically should do the following
$ cabal update
$ cabal install VKHS
-Note, that VKHS uses curlhs and should be linked with libcurl.so. Normally,
-cabal handles it without problems.
-
Installing from source
----------------------
@@ -54,29 +53,33 @@ Developing using Nix
--------------------
The author of this project uses [Nix](http://nixos.org) as a main development
-platform. Typical development procedure includes the following steps:
+platform. The `default.nix` file contain Nix expression describing the environment
+
+#### Entering Nix shell environment
$ git clone https://github.com/grwlf/vkhs
$ cd vkhs
- $
$ nix-shell
- .. Entering Nix shell environment
+#### Usual development
$ ghci -isrc:app/vkq:app/common
- $ exit
+ $ cabal install
+ $ ^D
- .. Now exiting from the Nix shell
+#### Returning to the system shell
+ $ ^D
$ nix-build
+ $ ls ./result
-The `default.nix` file contain Nix expression describing the environment
Building ctags file
-------------------
-`./mktags.sh` script may be used to build ctags file. It used `haskdogs` tool,
-which should be installed from Hackage.
+`./mktags.sh` script may be used to build ctags `tags` file supported by many
+text editors. The script uses `hasktags` via `haskdogs` tools, available on
+Hackage.
$ haskdogs
@@ -86,34 +89,35 @@ VKQ command line application
============================
`vkq` is a command line tool which demonstrates API usage. It can be used for
-logging in, downloading music and reading wall messages. Call `vkq --help` or
+logging in, -downloading music- and reading wall messages. Call `vkq --help` or
`vkq --help [command]` to read online help.
-Log in to VK
-------------
+Logging in to VK
+----------------
+
+In order to send API requests, the VK client typically needs an access token.
+`vkq` receives it as a result of signing in. Once received, the token may be
+saved to `VKQ_ACCESS_TOKEN` environment variable, into `.vkhs-access-token`
+file or passed to future instances directly using `-a` argument.
-Here is an example session: Login first
+#### Saving access token in the environment variable
$ vkq login user@mail.org pass123
d8a41221616ef5ba19537125dc0349bad9d529fa15314ad765911726fe98b15185ac41a7ca2c62f3bf4b9
-
-VKQ returns three values. First one is an access token required to execute all
-API requests. `vkq` tries to reads it from `VKQ_ACCESS_TOKEN` environment variable or
-from `.vkhs-access-token` file (may be changed using options).
-
$ export VKQ_ACCESS_TOKEN=d785932b871f096bd73aac6a35d7a7c469dd788d796463a871e5beb5c61bc6c96788ec2
-VKQ may cache the access tokein into a state file:
+Alternatively, using `--eval` option
- $ vkq login --access-token-file=.access-token
+ $ eval `vkq login user@mail.org pass123 --eval`
- .. VKQ will ask for email/password and cache the access token
+#### Saving access token to file
- $ vkq call groups.search q=Beatles --pretty --access-token-file=.access-token
+ $ vkq login --access-token-file=.access-token
-Latest versions of the library have `--access-token-flag` option enabled by
-default. Set it to empty value to disable the caching feature.
+VKQ will ask for email/password and cache the access token into a file. Newer
+versions of VKHS have `--access-token-flag` option enabled by default. Set it
+to empty value to disable the caching feature.
Performing custom API calls
diff --git a/VKHS.cabal b/VKHS.cabal
index 6cfb689..cc31486 100644
--- a/VKHS.cabal
+++ b/VKHS.cabal
@@ -1,6 +1,6 @@
name: VKHS
-version: 1.8.3
+version: 1.8.4
synopsis: Provides access to Vkontakte social network via public API
description:
Provides access to Vkontakte API methods. Library requires no interaction
diff --git a/src/Web/VKHS.hs b/src/Web/VKHS.hs
index 04680cb..c4f8125 100644
--- a/src/Web/VKHS.hs
+++ b/src/Web/VKHS.hs
@@ -74,7 +74,7 @@ type Guts x m r a = ReaderT (r -> x r r) (ContT r m) a
-- early exit by the means of continuation monad. VK encodes a coroutine which
-- has entry points defined by 'Result' datatype.
--
--- See also 'runVK' and 'defaultSuperwiser`.
+-- See also 'runVK' and 'defaultSupervisor`.
--
-- * FIXME Re-write using modern 'Monad.Free'
newtype VK r a = VK { unVK :: Guts VK (StateT State (ExceptT Text IO)) r a }
@@ -91,7 +91,7 @@ stepVK :: VK r r -> StateT State (ExceptT Text IO) r
stepVK m = runContT (runReaderT (unVK (VKHS.catch m)) undefined) return
-- | Run VK monad @m@ and handle continuation requests using default
--- algorithm. @defaultSuperwiser@ would relogin on invalid access token
+-- algorithm. @defaultSupervisor@ would relogin on invalid access token
-- condition, ask for missing form fields (typically - an email/password)
--
-- See also 'runVK'
@@ -99,8 +99,8 @@ stepVK m = runContT (runReaderT (unVK (VKHS.catch m)) undefined) return
-- * FIXME Store known answers in external DB (in file?) instead of LoginState
-- FIXME dictionary
-- * FIXME Handle capthas (offer running standalone apps)
-defaultSuperviser :: (Show a) => VK (R VK a) (R VK a) -> StateT State (ExceptT Text IO) a
-defaultSuperviser = go where
+defaultSupervisor :: (Show a) => VK (R VK a) (R VK a) -> StateT State (ExceptT Text IO) a
+defaultSupervisor = go where
go m = do
GenericOptions{..} <- toGenericOptions <$> get
res <- stepVK m
@@ -143,7 +143,7 @@ defaultSuperviser = go where
case er_code of
NotLoggedIn -> do
alert $ "Attempting to re-login"
- at <- defaultSuperviser (login >>= return . Fine)
+ at <- defaultSupervisor (login >>= return . Fine)
modifyAccessToken at
go (k $ ReExec m args)
TooManyRequestsPerSec -> do
@@ -151,7 +151,7 @@ defaultSuperviser = go where
go (k $ ReExec m args)
ErrorCode ec -> do
alert $ "Unhandled error code " <> tshow ec <> "\n"
- <> "Consider improving 'defaultSuperwiser' or applying \n"
+ <> "Consider improving 'defaultSupervisor' or applying \n"
<> "custom error filters using `apiH` ,`apiHS` or their \n"
<> "high-level wrappers `apiSimpleH` / `apiSimpleHM`"
lift $ throwError res_desc
@@ -160,14 +160,14 @@ defaultSuperviser = go where
alert $ "Unsupervised error: " <> res_desc
lift $ throwError res_desc
--- | Run login procedure using 'defaultSuperwiser'. Return 'AccessToken' on
+-- | Run login procedure using 'defaultSupervisor'. Return 'AccessToken' on
-- success
runLogin :: GenericOptions -> ExceptT Text IO AccessToken
runLogin go = do
s <- initialState go
- evalStateT (defaultSuperviser (login >>= return . Fine)) s
+ evalStateT (defaultSupervisor (login >>= return . Fine)) s
--- | Run the VK monad @m@ using generic options @go@ and 'defaultSuperwiser'.
+-- | Run the VK monad @m@ using generic options @go@ and 'defaultSupervisor'.
-- Perform login procedure if needed. This is an mid-layer runner, consider
-- using 'runVK' instead.
runAPI :: Show b => GenericOptions -> VK (R VK b) b -> ExceptT Text IO b
@@ -177,14 +177,14 @@ runAPI go@GenericOptions{..} m = do
at <- readInitialAccessToken >>= \case
Nothing ->
- defaultSuperviser (login >>= return . Fine)
+ defaultSupervisor (login >>= return . Fine)
Just at ->
pure at
modifyAccessToken at
- defaultSuperviser (m >>= return . Fine)
+ defaultSupervisor (m >>= return . Fine)
--- | Run the VK monad @m@ using generic options @go@ and 'defaultSuperwiser'
+-- | Run the VK monad @m@ using generic options @go@ and 'defaultSupervisor'
runVK :: Show a => GenericOptions -> VK (R VK a) a -> IO (Either Text a)
runVK go = runExceptT . runAPI go
diff --git a/src/Web/VKHS/API/Base.hs b/src/Web/VKHS/API/Base.hs
index 94de399..34050b6 100644
--- a/src/Web/VKHS/API/Base.hs
+++ b/src/Web/VKHS/API/Base.hs
@@ -135,7 +135,7 @@ api m args = do
Left e -> terminate (JSONParseFailure' j e)
-- | Invoke the request, in case of failure, escalate the probelm to the
--- superwiser. The superwiser has a chance to change the arguments
+-- supervisor. The superwiser has a chance to change the arguments
apiR :: (Aeson.FromJSON a, MonadAPI m x s)
=> MethodName -- ^ API method name
-> MethodArgs -- ^ API method arguments
@@ -155,7 +155,7 @@ apiR m0 args0 = go (ReExec m0 args0) where
go recovery
-- | Invoke the request, in case of failure, escalate the probelm to the
--- superwiser. The superwiser has a chance to change the arguments
+-- supervisor. The superwiser has a chance to change the arguments
apiHM :: forall m x a s . (Aeson.FromJSON a, MonadAPI m x s)
=> MethodName -- ^ API method name
-> MethodArgs -- ^ API method arguments