VKHS: Provides access to Vkontakte social network via public API

This is a package candidate release! Here you can preview how this package release will appear once published to the main package index (which can be accomplished via the 'maintain' link below). Please note that once a package has been published to the main package index it cannot be undone! Please consult the package uploading documentation for more information.

[maintain]

Provides access to Vkontakte API methods. Library requires no interaction with the user during Implicit-flow authentication.


[Skip to ReadMe]

Properties

Versions0.0.1, 0.0.2, 0.0.3, 0.1.0, 0.1.1, 0.1.2, 0.1.3, 0.1.4, 0.1.5, 0.1.6, 0.2.0, 0.3.0, 0.3.1, 0.3.2, 0.3.3, 0.5.0, 0.5.1, 0.5.2, 0.5.3, 0.5.4, 0.5.5, 0.5.6, 0.5.7, 1.6.0, 1.6.1, 1.6.2, 1.6.3, 1.6.4, 1.7.0, 1.7.1, 1.7.2, 1.7.3, 1.8, 1.8.1, 1.8.2, 1.8.3, 1.8.4, 1.9, 1.9.1, 1.9.2, 1.9.2
Change logCHANGELOG.md
Dependenciesaeson, aeson-pretty, base (>=4.6 && <5), bytestring, case-insensitive, clock, containers, data-default-class, directory, filepath, flippers, hashable, http-client, http-client-tls, http-types, mtl, network-uri, optparse-applicative, parsec, pipes, pipes-http, pretty-show, process, regexpr, scientific, split, tagsoup, text, time, utf8-string, vector, VKHS [details]
LicenseBSD-3-Clause
CopyrightCopyright (c) 2012, Sergey Mironov
AuthorSergey Mironov
Maintainergrrwlf@gmail.com
CategoryWeb
Home pagehttp://github.com/grwlf/vkhs
Executablesvkq
UploadedTue Jan 15 21:33:31 UTC 2019 by SergeyMironov

Modules

Downloads

Maintainers' corner

For package maintainers and hackage trustees


Readme for VKHS-1.9.2

[back to package description]

VKHS

VKHS provides access to Vkontakte 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 VK API methods.

Features

TODO

Installing

TODO: Drop a note about Stack

Installing from Hackage

In order to install VKHS, one typically should do the following

$ cabal update
$ cabal install VKHS

Installing from source

$ git clone https://github.com/grwlf/vkhs
$ cd vkhs
$ cabal install

Developing using Nix

The author of this project uses Nix as a main development platform. The default.nix file contain Nix expression describing the environment

Developing via Nix shell environment

TODO: Check and document the usage of cabal repl with this package

$ git clone https://github.com/grwlf/vkhs
$ cd vkhs
$ nix-shell         # Entering NIX development shell
# ./ghci.sh         # GHCI wrapper script
> :lo Main          # Usual development
> ^D
# cabal install     # Shell provides access to cabal
# cabal sdist
# ^D
$ ...

Usual development

$ ghci -isrc:app/vkq:app/common
$ ^D
$ cabal install

Building ctags file

./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

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 vkq command --help to read online help.

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.

Saving access token in the environment variable

$ vkq login user@mail.org pass123
d8a41221616ef5ba19537125dc0349bad9d529fa15314ad765911726fe98b15185ac41a7ca2c62f3bf4b9
$ export VKQ_ACCESS_TOKEN=d785932b871f096bd73aac6a35d7a7c469dd788d796463a871e5beb5c61bc6c96788ec2

Alternatively, result may be achieved using --eval option

$ eval `vkq login user@mail.org pass123 --eval`

Saving access token to file

VKQ will 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.

Performing API calls

vkq allows user to call arbitrary API method. The generic interface is as follows:

$ vkq api --help
Usage: vkq api [--verbose] [--req-per-sec N] [--interactive] [--appid APPID]
               [--user USER] [--pass PASS] [-a ACCESS_TOKEN]
               [--access-token-file FILE] METHOD [PARAMS] [--pretty]
  Call VK API method

Available options:
  --verbose                Be verbose
  --req-per-sec N          Max number of requests per second
  --interactive            Allow interactive queries
  --appid APPID            Application ID, defaults to VKHS
  --user USER              User name or email
  --pass PASS              User password
  -a ACCESS_TOKEN          Access token. Honores VKQ_ACCESS_TOKEN environment
                           variable
  --access-token-file FILE Filename to store actual access token, should be used
                           to pass its value between sessions
  METHOD                   Method name
  PARAMS                   Method arguments, KEY=VALUE[,KEY2=VALUE2[,,,]]
  --pretty                 Pretty print resulting JSON
  -h,--help                Show this help text

The session may look like the following:

$ vkq api 'users.get'
{"response":[{"first_name":"Сергей","uid":222222,"last_name":"Миронов"}]}

$ vkq api 'messages.send' 'user_id=333333' 'message="Hi there!!!"'
{"response":57505}

$ vkq api 'groups.search' 'q=Haskell'
{
    "response": [
        30,
        {
            "screen_name": "ml_mat_asm",
            "photo": "https://pp.userapi.com/c638217/v638217626/54113/v5Ib71-dDzo.jpg",
            "is_closed": 0,
            "photo_medium": "https://pp.userapi.com/c638217/v638217626/54112/Nu_si987vOc.jpg",
            "name": "Matlab | Assembler | MathCAD | Haskell | Prolog",
            "photo_big": "https://pp.userapi.com/c638217/v638217626/54111/HGnUbgUorVU.jpg",
            "gid": 78651325,
            "is_admin": 0,
            "is_member": 0,
            "type": "page"
        },
        ...
}

VKHS library/runhaskell mode

Starting from 1.7.2 the library supports runhaskell-mode.

#!/usr/bin/env runhaskell
{-# LANGUAGE RecordWildCards #-}

import Web.VKHS
import Web.VKHS.Imports

main :: IO ()
main = runVK_ defaultOptions $ do
  Sized cnt cs <- getCountries
  forM_ cs $ \Country{..} -> do
    liftIO $ tputStrLn co_title

When executed, the program asks for login/password and outputs list of countries known to VK. getCountries and several other methods are defined in Web.VKHS.API.Simple.

The distribuption contains ./app/runhaskell folder with a couple of examples.

Debugging

Verbosity may be increased using --verbose flag or o_verbose field of GenericOptions. Login automata saves latest.html file during operation.

References

License

BSD3 license

Copyright (c) 2018, Sergey Mironov grrwlf@gmail.com