radium

README

radium

radium is a platform (client and optional server) for viewing reference articles, cheat sheets etc. right from a shell. radium is written in Go (Golang)

Install

1. Download the latest pre-built binary for your platform from releases page.
2. Run the binary! (Optionally, create a radium.yaml file in ~ to customize)

Build

radium requires Go 1.8+ to build. Simply run make command in the source directory to build and install the binary into your $GOPATH/bin directory. If you just want to build the binary, run make build

Run

You can run radium --help to see the list of available commands.

Querying from command-line

radium query "append file in go"

radium query dir --attr platform:windows

radium query go

--attr is not part of radium framework but part of the source implementation itself. Weather to consume the attributes or not is decided by the source implementation.

Querying from curl

For this, you need to run radium in server mode first using the command: radium serve --addr=localhost:8080

Then

curl "localhost:8080/search?q=append+file+in+go"

curl "localhost:8080/search?q=dir&platform=windows"

curl "localhost:8080/search?q=go"

When using http api, all query parameters except q and strategy will be assumed to be attributes

Running as Clipboard Monitor

Run radium serve --clipboard to start radium in server+clipboard mode (pass --addr="" to run in clipboard-only mode).

Now, everytime you copy some text into clipboard (which is less than 5 words), radium is going to run a query and try to find some results. If a result is found, it will be pasted back into the clipboard

How it works?

radium works by querying/scraping different knowledge sources (e.g. tldr-pages, LearnXInYMinutes etc.). A Source in radium is a Go interface and can be implemented to add new references to provide more relevant results.

type Source interface {
  Search(query Query) ([]Article, error)
}

Currently following implementations are available:

1. sources.TLDR using the awesome tldr-pages project
2. sources.LearnXInY using the awesome Learn X In Y Minutes project
3. cheatsh.CheatSh using the awesome cheat.sh project
4. sources.Radium which can be used to query other radium servers to enable distributed setup
5. wikipedia.Wikipedia which queries and extracts first paragraph from Wikipedia
6. duckduckgo.DuckDuckGo which uses DuckDuckGo Instant Answer API

See sources/README.md for more information

TODO:

• Make sources configurable
  • sources to be used should be configurable per instance
• a configurable caching mechanism to enable offline usage
• Add more sources
  • Wikipedia
  • DuckDuckGo
• Enable markdown to console colored output ?
• Enable clipboard monitoring
  • everytime user copies a string, run radium query
  • if a result is available within certain time window, replace the clipboard content with the solution
  • enable query only if clipboard text is in special format to reduce unwanted paste-backs

Documentation

Index

• Constants
• type Article
  • func (article Article) Validate() error
• type Cache
• type ClipboardMonitor
  • func (cbm *ClipboardMonitor) Run(ctx context.Context) error
• type Concurrent
  • func NewConcurrent(logger Logger) *Concurrent
  • func (con Concurrent) Execute(ctx context.Context, query Query, sources []RegisteredSource) ([]Article, error)
• type Instance
  • func New(cache Cache, logger Logger) *Instance
  • func (ins Instance) GetSources() []RegisteredSource
  • func (ins *Instance) RegisterSource(name string, src Source) error
  • func (ins *Instance) RegisterStrategy(name string, strategy Strategy)
  • func (ins Instance) Search(ctx context.Context, query Query, strategyName string) ([]Article, error)
• type Logger
• type NthResult
  • func NewNthResult(n int, logger Logger) *NthResult
  • func (nth *NthResult) Execute(ctx context.Context, query Query, srcs []RegisteredSource) ([]Article, error)
• type Query
  • func (query Query) Validate() error
• type RegisteredSource
• type Server
  • func NewServer(ins *Instance, defaultStrategy string) *Server
  • func (srv Server) ServeHTTP(wr http.ResponseWriter, req *http.Request)
• type Source
• type Strategy

Constants

const (
	Strategy1st        = "1st"
	StrategyConcurrent = "concurrent"
)

Default registered strategies

Types

type Article

type Article struct {
	// Title should represent a short title or a summary of the
	// content
	Title string `json:"title"`

	// Content should contain the body of the article which may
	// be a snippet, wiki article, answer etc.
	Content string `json:"content"`

	// ContentType should contain the type of the content returned
	// so that radium can use that info to render the content. It
	// should be one of markdown, json, yaml, html
	ContentType string `json:"content_type"`

	// Attribs can contain type of the article, keywords etc.
	Attribs map[string]string `json:"attribs"`

	// License can contain name of the license if applicable
	License string `json:"license"`

	// Source should contain the name of the registered source
	// which returned this article. This will be added automatically
	// by radium.
	Source string `json:"source"`
}

Article represents a radium article which can be a snippet, wiki, answer etc.

func (Article) Validate

func (article Article) Validate() error

Validate the article model

type Cache

type Cache interface {
	Source

	// Set should store the given pair in a caching
	// backend for fast access. If an entry with same
	// query already exists, it should be replaced
	// with the new results slice
	Set(q Query, rs []Article) error
}

Cache implementation is responsible for caching a given query-results pair for later use

type ClipboardMonitor

type ClipboardMonitor struct {
	MaxWords int
	Interval time.Duration
	Instance *Instance
	// contains filtered or unexported fields
}

ClipboardMonitor monitors the system clipboard and tries to use clipboard content as queries to radium. If the number of words in clipboard content is more than the maxWords, then ClipboardMonitor will not perform a radium query with it.

func (*ClipboardMonitor) Run

func (cbm *ClipboardMonitor) Run(ctx context.Context) error

Run starts an infinite for loop which continuously monitors the system clipboard for changes. Run() can be invoked as a goroutine, and a context can be passed in for stopping the monitor.

type Concurrent

type Concurrent struct {
	Logger
}

Concurrent is a radium strategy implementation.

func NewConcurrent

func NewConcurrent(logger Logger) *Concurrent

NewConcurrent initializes a concurrent radium strategy

func (Concurrent) Execute

func (con Concurrent) Execute(ctx context.Context, query Query, sources []RegisteredSource) ([]Article, error)

Execute the query against given list of sources concurrently. This strategy ignores the source errors and simply logs them.

type Instance

type Instance struct {
	Logger
	// contains filtered or unexported fields
}

Instance represents an instance of radium

func New

func New(cache Cache, logger Logger) *Instance

New initializes an instance of radium

func (Instance) GetSources

func (ins Instance) GetSources() []RegisteredSource

GetSources returns a list of registered sources

func (*Instance) RegisterSource

func (ins *Instance) RegisterSource(name string, src Source) error

RegisterSource adds a new source to the query sources

func (*Instance) RegisterStrategy

func (ins *Instance) RegisterStrategy(name string, strategy Strategy)

RegisterStrategy adds a new source to the query sources

func (Instance) Search

func (ins Instance) Search(ctx context.Context, query Query, strategyName string) ([]Article, error)

Search using given query and return results if any

type Logger

type Logger interface {
	Debugf(format string, args ...interface{})
	Infof(format string, args ...interface{})
	Warnf(format string, args ...interface{})
	Errorf(format string, args ...interface{})
	Fatalf(format string, args ...interface{})
}

Logger implementation should provide logging functionality to the radium instance. Log levels should be managed externally.

type NthResult

type NthResult struct {
	Logger
	// contains filtered or unexported fields
}

NthResult implements a radium search strategy. This strategy executes search in the given order of sources and stops at nth result or if all the sources are executed.

func NewNthResult

func NewNthResult(n int, logger Logger) *NthResult

NewNthResult initializes NthResult strategy with given n

func (*NthResult) Execute

func (nth *NthResult) Execute(ctx context.Context, query Query, srcs []RegisteredSource) ([]Article, error)

Execute each source in srcs until n results are obtained or all sources have been executed. This strategy returns on first error.

type Query

type Query struct {
	// Text is the primary search criteria. Sources must
	// use this to find relevant results
	Text string `json:"text"`

	// Attribs can be used by sources to further filter down
	// the results
	Attribs map[string]string `json:"attribs"`
}

Query represents a user query for a post

func (Query) Validate

func (query Query) Validate() error

Validate for empty or invalid queries

type RegisteredSource

type RegisteredSource struct {
	Name string
	Source
}

RegisteredSource embeds given Source along with the registered name.

type Server

type Server struct {
	Logger
	// contains filtered or unexported fields
}

Server represents an instance of HTTP API server

func NewServer

func NewServer(ins *Instance, defaultStrategy string) *Server

NewServer initializes the http API server with given instance of Radium

func (Server) ServeHTTP

func (srv Server) ServeHTTP(wr http.ResponseWriter, req *http.Request)

type Source

type Source interface {
	Search(ctx context.Context, q Query) ([]Article, error)
}

Source implementation is responsible for providing external data source to query for results.

type Strategy

type Strategy interface {
	Execute(ctx context.Context, query Query, sources []RegisteredSource) ([]Article, error)
}

Strategy implementation is responsible for performing queries against given set of sources using a particular approach.