LanguageColours (LanguageColours v1.1.0) View Source

LanguageColours offers an API for retrieving colours for programming languages based on GitHub colour data (or some other dataset).

iex> LanguageColours.get("Ada", :my_db)
"#02f88c"

To install, add LanguageColours as a dependency of your Mix project:

defp deps do
  [
    {:language_colours, "~> 1.0.0"},
    ...
  ]
end

Databases

LanguageColours can be served by different databases. Databases must conform to the LanguageColours.Database behaviour. There is one database included, the LanguageColours.ETSDatabase, that uses ETS to store the language colour data. As a source, it uses a JSON file in the format found in the https://github.com/ozh/github-colors/ repo. This file can be downloaded in a development environment with mix language.colours.dl.data.

Fallback colours

If a language is not found in the database, nil will be returned by default. Optionally, the Rainbow package can be used to generate a random colour based on the language name as fallback. To use the fallback, set the database configuration option :fallback to true, and install Rainbow as a dependency:

defp deps do
  [
    {:rainbow, "~> 0.1.0"},
    ...
  ]
end

Configuration

To configure a database, you can give the configuration directly in the function call:

config = %{...}
LanguageColours.get("C++", config)

Or you can configure database aliases in your favourite config file (runtime.exs is recommended so you don't need to recompile the app on config changes):

# Config file
config :language_colours,
  databases: %{
    foo_db: %{
      ...
    }
  }

Then you can use this name in the function call:

LanguageColours.get("COBOL", :foo_db)

The supported configuration options are:

  • :json_parser: Module name of the JSON parser to use. Default is Jason.
  • :databases: An atom-keyed map of database specific configurations, which can be maps themselves or keyword lists.

The database specific configuration options are:

  • :db: The database module to use. This option is required.
  • :fallback: Boolean specifying whether to get a fallback colour from Rainbow or not, if language was not found in database. Default false.

Additionally, the ETSDatabase has its own database specific options:

  • :file: Path to the file to read the JSON data from.
  • :server_name: The name to use for the database process. Must conform to GenServer.name/0. By default the module name is used.
  • :ets_table: Name of the ETS table to use.

Setting up using ETSDatabase

First configure your database. Then start the database in your supervisor using the LanguageColours.ETSDatabase.startup_options/1 function like this:

config = LanguageColours.config!(:foo_db)
children = [
  ...,
  {LanguageColours.ETSDatabase, LanguageColours.ETSDatabase.startup_options(config)},
  ...
]

Alternatively you can directly give the LanguageColours.ETSDatabase.Options.t/0 struct as the argument.

Link to this section Summary

Functions

Retrieve the configuration for the given database name.

Get the colour corresponding to the given language.

Update the database specified in the argument.

Link to this section Functions

Specs

config!(atom()) :: map()

Retrieve the configuration for the given database name.

If the database is not configured, an error will be raised.

Link to this function

get(language, db_or_config)

View Source

Specs

get(String.t(), atom() | keyword() | map()) :: LanguageColours.Colour.t() | nil

Get the colour corresponding to the given language.

The database specified in the second argument (as configuration or preconfigured database name) is used to fetch the language. If the language is not found and fallback is not configured, nil is returned.

Specs

update(atom() | keyword() | map()) :: :ok

Update the database specified in the argument.

The argument may be a preconfigured database name or a configuration map/kwlist.