iloa

Introduction

iloa is Samoan for knowing

iloa is a powerful tool for gaining knowledge from the command line. It queries DuckDuckGo, Encyclopedia of Life, Weather Underground, Wikipedia, Wolfram|Alpha, and more through meta-searches. See the wiki for more info. iloa goes great with leximaven.

Installation

To initialize the config file and load themes, your NODE_PATH environment variable must point to the lib/node_modules directory of the Node.js installation. You can set this path automatically like this:

export NP=$(which node)
export BP=${NP%bin/node} #this replaces the string '/bin/node'
export LP="${BP}lib/node_modules"
export NODE_PATH="$LP"

Provided these lines are towards the end of the shell initialization file (at least after any NVM stuff) this should work for a system installation of Node.js and nvm.

Add all of this to .bashrc, .zshrc, Windows env, etc. then:

npm install -g iloa
iloa config init

Usage

iloa has a built-in help system for CLI parameters and options. Access it with iloa -h|--help [command] [subcommand]. There is also the wiki.

Here are some examples:

// Get DuckDuckGo instant answers for Infected Mushroom
iloa ddg 'Infected Mushroom'

// Get Encyclopedia of Life pages for Homo sapiens
iloa eol page 327955 -n -d -m -y -r -x

// Get Weather Underground conditions and forecast for Tampa Knight Airport
iloa wu -e conditions,forecast KTPF

// Get Wolfram|Alpha computation of doppler shift
iloa wa 'doppler shift'

// Get Wikipedia article for George Gurdjieff
iloa wp 'George Gurdjieff'

See the tests for more.

Resources

The following links can help you use iloa or perform related tasks.

Contributing

See CONTRIBUTING.

Gratitude

Many thanks to all contributors to the libraries used in this project! And thanks to the creators and maintainers of the APIs that this tool consumes. DuckDuckGo, Encyclopedia of Life, Weather Underground, Wikipedia, and Wolfram|Alpha are awesome!

Table of Contents

Completion

iloa command: completion, comp

Bash instructions

Run iloa comp >> ~/.bashrc, then source ~/.bashrc to enable shell completion for iloa commands and options.

Zsh instructions

To Zsh read your bash script, add to ~/.zshrc:
autoload bashcompinit
bashcompinit

Now run iloa comp >> ~/.zshrc and source ~/.zshrc.

Configuration

iloa can get and set values in the configuration file once it’s been initialized. iloa uses the dotty library to allow dot notation for nested values. See the FAQ for why I chose noon for the configuration file format.

iloa command: configuration, config, conf

iloa subcommands:

  • init, i - Creates configuration file in home directory (~/.iloa.noon)
  • get, g - Gets a value for a given key. Accepts dot notation for nested values.
  • set, s - Sets a given key to a given value. Accepts dot notation for nested values.

Examples

For single values like verbose you can just do iloa config set verbose true. For nested properties, use dot notation like so:

1
2
3
4
5
$ iloa config get wiki.intro
Option wiki.intro is true.
$ iloa config set wiki.intro true
Set option wiki.intro to true.

Saving flags

By default, the merge option is set to true, so CLI flags will be merged with the configuration from file. If you pass -s|–save with this, the config file will be overwritten with the current flags. If merge is set to false, the config file will always be used and –save won’t work. To restore all defaults run iloa config init --force.

Editing

Refer to the noon syntax guide. When editing the configuration file manually, please remember that empty strings are denoted by two pipes: || and 2 or more spaces separate keys from values.

DuckDuckGo Instant Answers

iloa command: duckduckgo, duck, dg

DDG’s API provides instant answers to arbitrary searches. In the case of a generalized term, a disambiguation will be returned:

1
iloa duck tool

Like Wikipedia, parentheses around a classification indicate specific articles, like so:

1
iloa duck 'Tool (band)'

  • Bangs - DuckDuckGo’s API also accepts bang redirects to over 8 thousand sites with a query interface. Example:

    iloa duck ‘!songmeaning Tool’

…redirects to songmeanings.com query for the band Tool.

You can contribute to better instant answers with the DuckDuckHack platform and join the community at duck.co.

Engine

  • chalk, ora, and yargonaut are used to style the terminal output.
  • moment manipulates timestamps for rate limiting.
  • good-guy-http gets and caches HTTP requests.
  • yargs is used for creating the CLI.
  • xml2js is used for XML format, and noon is used for all other formats.

Encyclopedia of Life

From eol.org:

Our knowledge of the many life-forms on Earth - of animals, plants, fungi, protists and bacteria - is scattered around the world in books, journals, databases, websites, specimen collections, and in the minds of people everywhere. Imagine what it would mean if this information could be gathered together and made available to everyone – anywhere – at a moment’s notice.

This dream is becoming a reality through the Encyclopedia of Life.

EOL in iloa

Learning to use EOL with iloa takes a little work, their API docs should help. Most commands take some kind of data identifier with a numeric value. Output is currently quite verbose, but informative.

iloa command: eol, life

EOL Subcommands:

  • collection, collect, col returns all metadata about a particular collection and the items it contains indexed by EOL
  • entry, en gives access to a single hierarchy indexed by EOL and its internal relationships
  • hierarchy, hier, hi given a hierarchy identifier, this method returns metadata about the hierarchy and lists the root taxa
  • info, i ping service status and lists the identifiers for all hierarchies supplied by content partners
  • metadata, meta, md returns all metadata about a particular data object (text, image or video) indexed by EOL
  • page, pg takes an EOL page identifier and returns the scientific name for that page, and optionally returns information about common names, media (text, images and videos), and references to the hierarchies which recognize the taxon described on the page
  • provider, pro, by get the EOL page IDs given a provider’s hierarchy_id and the provider’s own unique identifier
  • search, match, query, se given a value for a specific element (e.g. scientific name=Homo sapiens), returns a paginated list of the EOL pages containing the search term

Not implemented:

  • hierarchy_entries_descendants Couldn’t find any IDs that gave descendant data

Frequently (or Never) Asked Questions

What is noon?

noon, or ‘nother ordinary object notation, is a human-readable data format created by monsterkodi. Despite noon being very new, I decided to use it for leximaven’s configuration file because it is incredibly terse, even more so than hjson and cson. This is me supporting a young project that I would like to see get wider recognition. It also makes it dead simple to load and save cson, json, plist, and yaml.

What do you mean by gaining knowledge?

Though this tool may be limited in some ways, it is not biased. Knowledge comes in many forms. I encourage you to seek other knowledge outside of this tool. There is no ultimate authority.

Features

  • Extensible
  • Configuration file in your home directory called .iloa.noon
  • Access configuration settings by passing commands, setting flags, or just editing the configuration file manually
  • Sensible command line defaults and aliases
  • XML parsing and building with xml2js
  • In-memory caching and other neat features handled by good-guy-http, which is based on request
  • Save data to CSON, JSON, noon, Plist, XML, and YAML
  • Instant Answers and bang redirects from DuckDuckGo
  • Most API functions from Encyclopedia of Life
  • Alerts, Almanac, Astronomy, Conditions, Forecast, Geolookup, Hourly, Tide, and Webcams from Weather Underground
  • Summaries and Full Articles from Wikipedia
  • Computations from Wolfram|Alpha
  • Automatic rate-limiting for Weather Underground & Wolfram|Alpha

New APIs

Adding new APIs to iloa is pretty straightforward. Look at the docs for yargs to understand the module format. Wikipedia has the simplest API, so it’s a good example of how to implement a new module.

Each module registers a command with yargs. The command string defines the command and arguments. The builder object defines our options. The handler function contains our command logic.

After configuration checks and theme loading, we assemble the URL from the parsed arguments, argv. good-guy-http fetches the JSON response. For each piece of data that is printed in the console, the same data is added to the tofile object. If --out is specified, this object is passed to tools.outFile which is then encoded and saved. Finally, if --save is specified, options are saved to configuration.

Overlap

There is some overlapping functionality internally between iloa commands and externally between leximaven & iloa.

  • DuckDuckGo Instant Answers often return Wikipedia articles.

  • Wolfram|Alpha can perform many of the same functions that leximaven can, such as definitions, related words, acronyms, anagrams, pattern matching, and rhymes.

Weather Underground

iloa command: weather, wunder, wu

More info about weather than you could ever want! See the API docs for detailed info.

Implemented features:

  • Alerts
  • Almanac
  • Astronomy
  • Current Conditions
  • Forecast
  • Forecast 10-day
  • Geolookup
  • Hourly forecast
  • Hourly 10-day
  • Tide
  • Webcams

Not implemented:

  • Current Hurricane
  • History
  • Planner
  • Radar/Satellite
  • Yesterday

API Limits:

  • 500/day
  • 10/minute

Wikipedia

iloa command: wikipedia, wiki, wp

A quick-and-dirty way to get just the article summary (flag -i/–intro) or the full article in MediaWiki markup. You could then pipe the MediaWiki markup into something like pandoc. See the API docs for more info.

Wolfram|Alpha

iloa command: wolfram, wolf, wa

W|A is a computational knowledge engine written in the Wolfram language which is written in Wolfram’s Mathematica language. This makes it possible to search complex scientific concepts in free-form natural language. Example:

1
iloa wolf 'doppler shift'

…returns the formula for calculating the change in pitch based on the formula:

1
f_o/f_s = c/(c+v_s)

…where f_o/f_s (frequency reduction factor), c is the speed of sound (340.3 m/s) and v_s is the speed of source away from the observer (10 m/s). The results include an image file link for the rendered LaTeX equation and an audio clip of the calculation on a sine wave.

API Limit:

  • 2000/month, caching results not allowed.