# -*- mode:org; mode:visual-line; coding:utf-8; -*-

*** KeyMap: A Hierarchical Key-Value Store for GNU Make

This library implements a hierarchical key-value store for GNU Make. It allows the user to:

- Map keys to values.

- For a given key prefix, list all valid next key components.

**** Usage

***** Place key-value pairs in a file (see [[SAMPLE_KEYS]]), one per line:

#+BEGIN_EXAMPLE
program_option|opt_1          --fast
program_option|opt_2          --very --accurate
reference|human|url           ftp://example.com/human.fa.gz
reference|human|md5sum        012345
reference|ecoli|url           ftp://example.com/ecoli.fa.gz
reference|human|md5sum        012345
dataset|human_1|url           ftp://example.com/human_1.tar.gz
dataset|human_1|md5sum        012345
dataset|human_1|reference     human
dataset|human_2|url           ftp://example.com/human_2.tar.gz
dataset|human_2|md5sum        012345
dataset|human_2|reference     human
dataset|ecoli_1|url           ftp://example.com/ecoli_1.tar.gz
dataset|ecoli_1|md5sum        012345
dataset|ecoli_1|reference     ecoli
#+END_EXAMPLE

Note:

- Everything up to the first whitespace is interpreted as the key.

- Everything after the first whitespace is interpreted as the value.

- The value may contain whitespace, but multiple consecutive spaces (including tabs) will be converted to a single space. (The lines are passed through =awk=.)

- Keys may include a key spearator (by default, =|=).

- The keys will be stored in GNU Make variables, and as such, they may not include: =:=, =#=, ===, or whitespace. See: [[https://www.gnu.org/software/make/manual/html_node/Using-Variables.html][Make Variables]].

- Do not use keys which end in a separator (e.g., =dataset|=). These are used internally to store valid next key components.

***** Load the key-value pairs in GNU Make:

#+BEGIN_EXAMPLE
KEYMAP_FILES = SAMPLE_KEYS
include /path/to/keymap.make
#+END_EXAMPLE

***** Retrieve value for a given key with =keymap_val=:

#+BEGIN_EXAMPLE
human.fa:
	wget $(call keymap_val,reference|human|url) -O- | gunzip >$@
#+END_EXAMPLE

***** Retrieve list of next key components for a given prefix with =keymap_key_list=:

#+BEGIN_EXAMPLE
define process_dataset
# ${1} = dataset
# ${2} = reference
...
endef
# ds = human_1 human_2 ecoli_1
# ref = human human ecoli
$(foreach ds,$(call keymap_key_list,dataset),\
$(foreach ref,$(call keymap_val,dataset|${ds}|reference),\
$(eval $(call process_dataset,${ds},${ref}))))
#+END_EXAMPLE

**** Influential Variables

These GNU Make variables should be set prior to including =keymap.make=.

- =KEYMAP_FILES= :: List of files containing key-values. Key-value pairs in later files override pairs (with the same key) in earlier files. If =KEYMAP_FILES= is not specified, keys will be loaded from =KEYS= and =KEYS.local= if they exist in the current directory.

- =KEYMAP_SEPARATOR= :: Key component separator. By default, =|=.

- =KEYMAP_PREFIX= :: Prefix added to all keys when storing them as GNU Make variables. By default, =KEYMAP=.

**** Example

For an example Makefile using the keys above, see [[sample.make]]. Run with =make -f sample.make=.

**** License

Released under the [[LICENSE][MIT license]].