From 433d9f2d0ed9dd8c76d9446b7a0096f74b8e38e3 Mon Sep 17 00:00:00 2001 From: Kenny Liu Date: Sat, 20 Dec 2014 01:38:25 +0700 Subject: [PATCH 01/10] Updated project description. --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index a90e95a1..ad7964a6 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # pallet.stevedore -An embedding of shell script in clojure. +Stevedore is a DSL for generating shell scripts using clojure. See [reference documentation](http://palletops.com/doc/reference/0.8/script/), From 023b0ee0aeb66bce5d6db69d1527e6ac2d183806 Mon Sep 17 00:00:00 2001 From: Kenny Liu Date: Sat, 20 Dec 2014 01:39:30 +0700 Subject: [PATCH 02/10] Added a `Why?` section in README to give a rationale. --- README.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/README.md b/README.md index ad7964a6..c313286c 100644 --- a/README.md +++ b/README.md @@ -9,6 +9,13 @@ and [annotated source](http://pallet.github.com/stevedore/marginalia/uberdoc.htm See [tests](https://github.com/pallet/stevedore/tree/develop/test/pallet/stevedore) for usage examples. +## Why? + +While there is nothing wrong with normal shell scripting, Stevedore allows the +ability to easily interpolate clojure values. As a consequence, we gain the +benefits of being able to flexibly parameterize scripts and tailor them to +target specific operating systems and their versions. + ## Installation stevedore is distributed as a jar, and is available in the From 90cfcafbd67dda740a3cd8ef2406b1019cada76a Mon Sep 17 00:00:00 2001 From: Kenny Liu Date: Sat, 20 Dec 2014 01:41:55 +0700 Subject: [PATCH 03/10] Added `Documentation` section to README. --- README.md | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index c313286c..4a653fa5 100644 --- a/README.md +++ b/README.md @@ -2,13 +2,6 @@ Stevedore is a DSL for generating shell scripts using clojure. - -See [reference documentation](http://palletops.com/doc/reference/0.8/script/), -[api documentation](http://pallet.github.com/stevedore/autodoc/index.html) -and [annotated source](http://pallet.github.com/stevedore/marginalia/uberdoc.html). - -See [tests](https://github.com/pallet/stevedore/tree/develop/test/pallet/stevedore) for usage examples. - ## Why? While there is nothing wrong with normal shell scripting, Stevedore allows the @@ -48,6 +41,14 @@ Installation is with lein or your favourite maven repository aware build tool. ``` +## Documentation + +See [reference documentation](http://palletops.com/doc/reference/0.8/script/), +[api documentation](http://pallet.github.com/stevedore/autodoc/index.html) +and [annotated source](http://pallet.github.com/stevedore/marginalia/uberdoc.html). + +See [tests](https://github.com/pallet/stevedore/tree/develop/test/pallet/stevedore) for usage examples. + ## License Licensed under [EPL](http://www.eclipse.org/legal/epl-v10.html) From 16034dd5a6faff9a771839347c12bfeb308b2f82 Mon Sep 17 00:00:00 2001 From: Kenny Liu Date: Sat, 20 Dec 2014 01:44:20 +0700 Subject: [PATCH 04/10] Removed broken `reference documentation` link from README. --- README.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/README.md b/README.md index 4a653fa5..68523bf0 100644 --- a/README.md +++ b/README.md @@ -43,8 +43,7 @@ Installation is with lein or your favourite maven repository aware build tool. ## Documentation -See [reference documentation](http://palletops.com/doc/reference/0.8/script/), -[api documentation](http://pallet.github.com/stevedore/autodoc/index.html) +See [api documentation](http://pallet.github.com/stevedore/autodoc/index.html) and [annotated source](http://pallet.github.com/stevedore/marginalia/uberdoc.html). See [tests](https://github.com/pallet/stevedore/tree/develop/test/pallet/stevedore) for usage examples. From 389c2ccc9536cf51c9534f509fb2b91f1989d071 Mon Sep 17 00:00:00 2001 From: Kenny Liu Date: Sat, 20 Dec 2014 01:48:47 +0700 Subject: [PATCH 05/10] Made capitalization of `Stevedore` consistent in README. --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 68523bf0..b7f87c23 100644 --- a/README.md +++ b/README.md @@ -11,7 +11,7 @@ target specific operating systems and their versions. ## Installation -stevedore is distributed as a jar, and is available in the +Stevedore is distributed as a jar, and is available in the [clojars repository](http://clojars.org/com.palletops/stevedore). Installation is with lein or your favourite maven repository aware build tool. From 27758a9d87c87960741e0abc69b6365f4746b1be Mon Sep 17 00:00:00 2001 From: Kenny Liu Date: Sat, 20 Dec 2014 02:14:42 +0700 Subject: [PATCH 06/10] Added `Support` section to README. --- README.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/README.md b/README.md index b7f87c23..9d85c6dd 100644 --- a/README.md +++ b/README.md @@ -48,6 +48,11 @@ and [annotated source](http://pallet.github.com/stevedore/marginalia/uberdoc.htm See [tests](https://github.com/pallet/stevedore/tree/develop/test/pallet/stevedore) for usage examples. +## Support + +- [Google Groups](http://groups.google.com/group/pallet-clj) +- [IRC](http://webchat.freenode.net/?channels=pallet) + ## License Licensed under [EPL](http://www.eclipse.org/legal/epl-v10.html) From b3fc96af71c834709e98c343a9f8e8b5ffc76071 Mon Sep 17 00:00:00 2001 From: Kenny Liu Date: Sat, 20 Dec 2014 17:47:59 +0700 Subject: [PATCH 07/10] Added examples. Examples are taken from http://hugoduncan.org/post/shell_scripting_in_clojure_with_pallet/ but updated to work. --- README.md | 193 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 193 insertions(+) diff --git a/README.md b/README.md index 9d85c6dd..a339b973 100644 --- a/README.md +++ b/README.md @@ -41,6 +41,199 @@ Installation is with lein or your favourite maven repository aware build tool. ``` +## Examples + +### Basic Usage + +Let's write a basic script; nothing fancy just a plain ole' thing you can +easily write in your scripting language of choice. Very static. + +```clojure +(use 'pallet.stevedore) + +(print + (with-script-language :pallet.stevedore.bash/bash + (script + ("ls" "/some/path") + (defvar x 1) + (println @x) + (defn foo [x] ("ls" @x)) + ("foo" 1) + (if (= a a) + (println "Reassuring") + (println "Ooops")) + (println "I am" @("whomai"))))) +``` + +Outputs: +```bash + # form-init7685875326394262653.clj:2 +ls /some/path + # form-init7685875326394262653.clj:3 +x=1 + # form-init7685875326394262653.clj:4 +echo ${x} +foo() { +x=$1 + # form-init7685875326394262653.clj:5 +ls ${x} +} + # form-init7685875326394262653.clj:6 +foo 1 + # form-init7685875326394262653.clj:7 +if [ "a" == "a" ]; then echo Reassuring;else echo Ooops;fi + # form-init7685875326394262653.clj:10 +echo I am $(whomai) +``` + +### Interpolating Clojure + +Here is where we start seeing some power. Notice everything escaped with `~` +gets evaluated as clojure code before becoming parts of arguments for `script`. + +```clojure +(print + (with-script-language :pallet.stevedore.bash/bash + (let [path "/some/path"] + (script + ("ls" ~path) + ("ls" ~(.replace path "some" "other")))))) +``` + +Outputs: + +```bash + # form-init7685875326394262653.clj:6 +ls /some/path + # form-init7685875326394262653.clj:7 +ls /other/path +``` + +### Generating Scripts + +That's cool, but here's one better. Let's do the same thing as the previous +snippet but let's generate the script using a function that takes a path as an +argument. This lets us generate a slightly different script with each new +argument. + +```clojure +(defn list-path [path] + "Replaces the \"some\" portion of path argument with the \"other\" string." + (script + ("ls" ~path) + ("ls" ~(.replace path "some" "other")))) + +(print (with-script-language :pallet.stevedore.bash/bash + (list-path "/some/path"))) +``` + +Outputs: + +```bash + # form-init7685875326394262653.clj:7 +ls /some/path + # form-init7685875326394262653.clj:8 +ls /other/path +``` + +```clojure +(print (with-script-language :pallet.stevedore.bash/bash + (list-path "/some/different/path"))) +``` + +Outputs: + +```bash + # form-init7685875326394262653.clj:7 +ls /some/different/path + # form-init7685875326394262653.clj:8 +ls /other/different/path +``` + +### Composing Scripts + +Concatenate scripts together using `do-script`. + +```clojure +(print (with-script-language :pallet.stevedore.bash/bash + (do-script + (list-path "/some/path") + (list-path "/some/different/path")))) +``` + +Outputs: + +```bash +# form-init7685875326394262653.clj:5 +ls /some/path + # form-init7685875326394262653.clj:6 +ls /other/path +# form-init7685875326394262653.clj:5 +ls /some/different/path + # form-init7685875326394262653.clj:6 +ls /other/different/path +``` + +Chain scripts together with `&&` using `chained-script`. + +```clojure +(print (with-script-language :pallet.stevedore.bash/bash + (chained-script + (list-path "/some/path") + (list-path "/some/different/path")))) +``` + +Outputs: + +```bash +# form-init7685875326394262653.clj:4 + # form-init7685875326394262653.clj:5 +ls /some/path + # form-init7685875326394262653.clj:6 +ls /other/path && \ +# form-init7685875326394262653.clj:5 + # form-init7685875326394262653.clj:5 +ls /some/different/path + # form-init7685875326394262653.clj:6 +ls /other/different/path +``` + +Chain your scripts and exit if the chain fails using `checked-script`. + +```clojure +(print (with-script-language :pallet.stevedore.bash/bash + (checked-script + (list-path "/some/path") + (list-path "/some/different/path")))) +``` + +Outputs: + +```bash +echo ' # form-init7685875326394262653.clj:5 +ls /some/path + # form-init7685875326394262653.clj:6 +ls /other/path +...'; +{ + # form-init7685875326394262653.clj:5 + # form-init7685875326394262653.clj:5 +ls /some/different/path + # form-init7685875326394262653.clj:6 +ls /other/different/path + + } || { echo '#> # form-init7685875326394262653.clj:5 +ls /some/path + # form-init7685875326394262653.clj:6 +ls /other/path + : FAIL'; exit 1;} >&2 +echo '#> # form-init7685875326394262653.clj:5 +ls /some/path + # form-init7685875326394262653.clj:6 +ls /other/path + : SUCCESS' +``` + ## Documentation See [api documentation](http://pallet.github.com/stevedore/autodoc/index.html) From 1c918735dffae852fdce1254ff365cdccd3a3221 Mon Sep 17 00:00:00 2001 From: Kenny Liu Date: Sat, 20 Dec 2014 19:34:05 +0700 Subject: [PATCH 08/10] Small change of wording: new -> different. --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index a339b973..63b14c7e 100644 --- a/README.md +++ b/README.md @@ -113,7 +113,7 @@ ls /other/path That's cool, but here's one better. Let's do the same thing as the previous snippet but let's generate the script using a function that takes a path as an -argument. This lets us generate a slightly different script with each new +argument. This lets us generate a slightly different script with each different argument. ```clojure From 0967102879b25afe4e400abcfc2904f9ff965c21 Mon Sep 17 00:00:00 2001 From: Kenny Liu Date: Tue, 23 Dec 2014 11:45:18 +0700 Subject: [PATCH 09/10] Changed Documentation in README to Further Reading. Added link to stevedore documentation on palletops site. Changed organization of Further Reading content. --- README.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 63b14c7e..a64a12ae 100644 --- a/README.md +++ b/README.md @@ -234,12 +234,12 @@ ls /other/path : SUCCESS' ``` -## Documentation +## Further Reading -See [api documentation](http://pallet.github.com/stevedore/autodoc/index.html) -and [annotated source](http://pallet.github.com/stevedore/marginalia/uberdoc.html). - -See [tests](https://github.com/pallet/stevedore/tree/develop/test/pallet/stevedore) for usage examples. +- [More examples and explanations](http://palletops.com/pallet/doc/reference/0.8/script/) +- [API documentation](http://pallet.github.com/stevedore/autodoc/index.html) +- [Annotated source](http://pallet.github.com/stevedore/marginalia/uberdoc.html) +- [More usage examples(tests)](https://github.com/pallet/stevedore/tree/develop/test/pallet/stevedore) ## Support From c22dde5cfada98e01ad590aa59eca1796825bf13 Mon Sep 17 00:00:00 2001 From: Kenny Liu Date: Sat, 31 Jan 2015 22:57:40 +0700 Subject: [PATCH 10/10] Added stevedore.bash require. --- README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/README.md b/README.md index a64a12ae..2f98331c 100644 --- a/README.md +++ b/README.md @@ -50,6 +50,7 @@ easily write in your scripting language of choice. Very static. ```clojure (use 'pallet.stevedore) +(require 'pallet.stevedore.bash) (print (with-script-language :pallet.stevedore.bash/bash