From ca486192d891b3f6c9de4f3444712aeba1567f13 Mon Sep 17 00:00:00 2001
From: dig <dig@p2p.legal>
Date: Thu, 11 Apr 2019 00:55:07 +0200
Subject: [PATCH] =?UTF-8?q?Mettre=20=C3=A0=20jour=20'README.md'?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 README.md | 122 +++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 121 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 339f5ad..c13558f 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,123 @@
 # esm-cli
 
-EcmaScript Module launcher
\ No newline at end of file
+EcmaScript Module launcher
+
+Lunch ES modules using cli, accessing a specific export function or data, passing parameters.
+
+## Install
+
+Just install module as a global command with npm (not yet published)
+`npm install -g esm-cli`
+
+Until it published on npm you can install globaly after a git clone:
+```
+git clone https://git.p2p.legal/dig/esm-cli.git
+cd esm-cli
+npm install -g .
+```
+
+You should get acces to a global `esm` command.
+
+## Usage
+
+`esm path/to/esm_file:export_name [params]`
+
+With esm-cli you can instanciate a full ES module file, executing it's content, and retreive an exported variable or execute an exported function. It understand returned promises or async function.
+
+### Get exported variables
+
+Let's write a simple ES module (myModule.js):
+
+```javascript
+export default 42
+export var user_config = {
+    some: "json"
+}
+```
+
+And let's use it in cli:
+
+```bash
+esm myModule
+> 42
+```
+Note: .js extension is not needed (nodejs resolver).
+
+In a bash file you can invoke some text return using command subsitutions:
+```bash
+#!/usr/bin/env bash
+es_var=$(esm myModule)
+echo "EcmaScript said: $es_var"
+```
+If only a path to the file is provided, the default export is returned in any.  
+You can access any named exports:
+```bash
+esm myModule:user_config
+> { "some": "json" }
+```
+
+### Use exported functions
+When the exported "thing" is a function (async or not), it is executed passing command line parameters if given.
+
+Imagine a simple ES module library (myLib.js):
+
+```javascript
+export default function hello()
+{
+    console.log( 'Hello world !' )
+}
+export function greet( params ) {
+    return `Hello ${params[0]}`
+}
+```
+Then you can write:
+```bash
+esm myLib
+> Hello world !
+```
+```bash
+esm myLib:greet Pierre
+> Hello Pierre !!
+```
+### Promise/async support
+
+If the returned result is a promise, because explicitly returned, or from an async function, esm-cli will take care of waiting it's resolution returning the resolved value (gently catching rejections showing nothing).
+
+### Parameters parsing
+
+Command line parameters are parsed into an Array before it is given to a called function.  
+This Array contains a list of strings corresponding to each string given without hyphen `-`:
+
+(myLib.js)
+```javascript
+export function showParams( params )
+{
+    console.log( params )
+}
+```
+
+```bash
+esm myLib:showParams param1 param2 param3
+> [ "param1", "param2", "param3" ]
+```
+
+... and this array is augmented with properties corresponding to hyphen params, with value or "true" if not:
+```bash
+esm myLib:showParams param1 param2 param3 -s --t -foo --bar -baz:42 --val=some
+> [ "param1", "param2", "param3", s: true, t: true, foo: true, bar: true, baz: 42, val: "some" ]
+```
+
+Note: order don't matters...
+
+You can then use ES destructuration to filter named paremeters:
+
+```javascript
+export function myAwesomeFunction( [ first, second, , forth ] ) // Array destructuration gets simple params
+{
+    console.log( first, second, forth )
+}
+export function myAwesomeFunction2( { foo, val, baz } ) // Object destructuration gets named params
+{
+    console.log( foo, val, baz )
+}
+```
\ No newline at end of file