#+TITLE: Ponsapi-cli
#+DATE: Sat Dec 28 12:48:54 CET 2019
#+AUTHOR: Lio Novelli
#+LICENSE: GPLv3.0
#+VERSION: 0.9

* Introduction

  There was no nice command line tool for translations to be found so I've
  written my own. I was frustrated by opening a new tab in browser whenever I
  wasn't able to remember a translation of a word. I use terminal a lot and
  ponsapi-cli is one of the micro optimisations that at the end of the day
  sum up (I hope).

  I gave a lot of attention to pretty printing results, but
  not so much care was spent to make the translation script fast. It is
  something that will be addressed in the future versions but until then
  all you get is "pretty printing".

* Usage

  ~trans [flags] <word>~

  To get help use flag ~-h~.

  ~-f~ option (fuzzy matching) helps if no results were found.

* Dependencies
  
  This script uses following tools:
  - curl
  - jq
  - recode
  - sed

* Installation 
  
  First you have to register at pons.com [[https://login.pons.com/login?return_to=https%253A%252F%252Fen.pons.com%252Fopen_dict%252Fpublic_api][api registration form]].

  Once you get your API secret key, create a file named ponsapi.config in one
  of these paths: ~$HOME, $HOME/.config or $HOME/.config/ponsapi-cli~. 

  Besides ~PONS_SECRET="<your-pons-secret>"~ line in your config file, you can
  specify other default parameters there as well (~PONS_DICT~ for dictionary -
  you can see a list of those by calling trans script with flag ~-o~ and
  ~PONS_LANG~ to specify in which language is the word you are looking
  translation for).

  Make your script executable and crate a symlink to it in your execution path.
  Simplier solution is to just a create ~alias~ in your ~.bashrc/.zshrc~ file
  (~alias trans="<path-to-script>/trans.sh"~)

* How it works

  Script creates a curl request to pons api and parses json response with jq.
  Json response can have 2 different structures depending on a results found in
  their dictionary. This complicates parsing a little bit but script has
  two functions written for parsing each of those two different structures
  and creates a unified json which is then used for pretty printing results.

  You can see raw results with ~-r~ flag. 

* Development
  - [[https://en.pons.com/p/files/uploads/API/API_Documentation.pdf][Pons api documentation]]

  I will rewrite this application in haskell once I found more time. Even before
  that I'll implement some error handling.

** to do
   - error handling
   - rewrite into haskell
   - ...
  
** done
   - no color option