VKHS 1.8.3 → 1.8.4

raw patch · 4 files changed

+58/−54 lines, 4 filesPVP: major bump suggested

API removals or changes: PVP suggests a major version bump

API changes (from Hackage documentation)

Files

• README.md +43/−39
• VKHS.cabal +1/−1
• src/Web/VKHS.hs +12/−12
• src/Web/VKHS/API/Base.hs +2/−2

@@ -2,31 +2,33 @@ ====  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,10 +41,7 @@     $ 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 @@ --------------------  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` 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+---------------- -Here is an example session: Login first+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. +#### 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

@@ -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

@@ -74,7 +74,7 @@ -- 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 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 @@ -- * 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 @@             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 @@                 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 @@         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 @@      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 

@@ -135,7 +135,7 @@     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 @@         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