From cad4cf931abf8934ae1f804fad180d69a770049d Mon Sep 17 00:00:00 2001
From: Fenris Wolf <fenris@folksprak.org>
Date: Thu, 17 Jul 2025 14:15:04 +0200
Subject: [PATCH] [add] readme

---
 readme.md | 82 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 82 insertions(+)
 create mode 100644 readme.md

diff --git a/readme.md b/readme.md
new file mode 100644
index 0000000..be27735
--- /dev/null
+++ b/readme.md
@@ -0,0 +1,82 @@
+# coin
+
+## Description
+
+transforms a template string to its refined version by substituting its placeholders with concrete values
+
+
+## Building
+
+### Requirements
+
+- shell interpreter
+
+
+### Instructions
+
+- execute `tools/build`
+
+
+## Installation
+
+### Requirements
+
+- shell interpreter
+
+
+### Instructions
+
+- (as `root`) execute `tools/install`
+
+
+## Usage
+
+### Requirements
+
+- Python 3 interpreter
+
+
+### Examples
+
+#### basic
+
+```
+echo '{{flowers}} are {{color}}' | coin -a 'flowers:roses' -a 'color:red'
+
+# roses are red
+```
+
+The same result can be produced by using multiple `coin` calls:
+
+```
+echo '{{flowers}} are {{color}}' | coin -a 'flowers:roses' | coin -a 'color:red'
+```
+
+In some contextes curly brackets might might be reserved or not available for other reasons. This can be mitigated by using different placeholder indicators:
+
+```
+echo '<<flowers>> are <<color>>' | coin -o '<<' -c '>>' -a 'flowers:roses' -a 'color:red'
+```
+
+
+#### file arguments
+
+```
+echo -n "cornflowers" > /tmp/flowers.txt
+echo -n "blue" > /tmp/color.txt
+echo '{{flowers}} are {{color}}' | coin -a 'flowers:@/tmp/flowers.txt' -a 'color:@/tmp/color.txt'
+
+# cornflowers are blue
+```
+
+
+#### data file
+
+```
+echo -e "flowers: daffodills\ncolor: yellow" > /tmp/data.yaml
+echo '{{flowers}} are {{color}}' | coin -d /tmp/data.yaml
+
+# daffodills are yellow
+```
+
+