This is an automated email from the ASF dual-hosted git repository.
npeltier pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/sling-site.git
The following commit(s) were added to refs/heads/master by this push:
new b318fec Update Sling Pipes documentation
b318fec is described below
commit b318fec46d49e956460fce1bbc2e0160e18066c2
Author: Nicolas Peltier <[email protected]>
AuthorDate: Thu Jan 28 17:14:27 2021 +0100
Update Sling Pipes documentation
some simplifications, switch to the text declaration in most cases (Pipes
4.1.2)
---
.../content/documentation/bundles/sling-pipes.md | 56 ++++-----
.../documentation/bundles/sling-pipes/bindings.md | 9 +-
.../bundles/sling-pipes/execution-monitoring.md | 9 +-
.../documentation/bundles/sling-pipes/logical.md | 75 ++++++------
.../documentation/bundles/sling-pipes/readers.md | 130 ++++++++-------------
.../documentation/bundles/sling-pipes/samples.md | 2 +-
.../documentation/bundles/sling-pipes/writers.md | 90 ++++++--------
7 files changed, 158 insertions(+), 213 deletions(-)
diff --git a/src/main/jbake/content/documentation/bundles/sling-pipes.md
b/src/main/jbake/content/documentation/bundles/sling-pipes.md
index 3adec26..1f67cae 100644
--- a/src/main/jbake/content/documentation/bundles/sling-pipes.md
+++ b/src/main/jbake/content/documentation/bundles/sling-pipes.md
@@ -8,62 +8,50 @@ Sling pipes is a tool set for doing extract - transform -
load operations by cha
## Introduction
-Sling Pipes can be seen as a language that optimizes communication between two
developers knowing sling terminology,
-just as they would talk about it, e.g.
+Sling Pipes can be seen as a language that takes profit of optimized
communication between two developers knowing sling terminology,
+e.g.
searching for resources with type "foo/bar" and setting property id to
3
Such sentence with that limited amount of words is enough between two sling
developers to understand fully what it is
-doing. However, implementing this as a servlet would take a lot more words,
risks of failure, complexity of deployement
-and would be more opaque, not talking about monitoring or execution common,
but complex features you'd like to add.
+doing. However, implementing that change with a computer language directly
will take much more words, risks of failure,
+complexity of deployement and would be more opaque, not talking about
monitoring or execution commons, but complex
+features you'd like to add.
With Sling Pipes, what you need to develop, and what is readable by another
developer is
- plumber.newPipe(resolver).$("foo/bar").write("id",3).build("/etc/demo")
+
plumber.newPipe(resolver).echo("content").$("foo/bar").write("id",3).build("/etc/demo")
this is enough to persist a pipe in `/etc/demo` that is executable as http,
java, groovy console script, or JMX.
-You can monitor it with JMX, logs, http, you'll have dry run possibility of
that execution for example, or asynchronous execution.
-You could also use a pipe to create a java-free json or csv servlet, or a list
component whose list possibilities are pipes accessed through the `PipeModel`
-
-or, if you are testing things from the command line, using a curl script named
"pipe"
-
- pipe "$ foo/bar | write id 3"
+You can monitor it with JMX, logs, http, you'll have dry run possibility of
that execution for example, or asynchronous execution.
+If it's a one-off execution, and you can access a groovy script or anything
you can use external command line tool like
[pipe](https://github.com/adobe/adobe-dx/blob/master/apps/scripts/pipe)
+to run
+ pipe "echo /content | $ foo/bar | write id=3"
+
+Those examples are using echo, find and
[write](/documentation/bundles/sling-pipes/writers.html#write-pipe-writeconf)
subpipes.
+
+You could also use a pipe to create a java-free json or csv servlet, or a list
component whose list possibilities are pipes accessed through the `PipeModel`
you can check some introductions at different adaptTo presentations:
-## AdaptTo introductions
+### AdaptTo introductions
-some presentations were made at the adaptTo conference, last two were:
+some presentations were made at the adaptTo conference, last three were:
+[latest presentation at a 2021 lightning
talk](https://adapt.to/2020/en/schedule/lightning-talks/sling-pipes-400-update.html).
This introduces
+the change of being able to manipulate pipes through command line.
+<iframe width="560" height="415"
src="https://www.youtube.com/embed/Z5UtXh9XzwY"; frameborder="0"
allow="autoplay; encrypted-media" allowfullscreen></iframe>
[General introduction at a 2017 lightning
talk](https://adapt.to/2017/en/schedule/lightning-talks/apache-sling-pipes.html).
-<iframe width="560" height="315"
src="https://www.youtube.com/embed/XcWMB26bMxA?start=666"; frameborder="0"
allow="autoplay; encrypted-media" allowfullscreen></iframe>
+<iframe width="560" height="415"
src="https://www.youtube.com/embed/XcWMB26bMxA?start=666"; frameborder="0"
allow="autoplay; encrypted-media" allowfullscreen></iframe>
and [latest news at a 2018 lightning
talk](https://adapt.to/2018/en/schedule/lightning-talks/whats-new-with-filters-pipes.html)
-<iframe width="560" height="315"
src="https://www.youtube.com/embed/LhxVE-56p2Y?start=122"; frameborder="0"
allow="autoplay; encrypted-media" allowfullscreen></iframe>
-
-## What is a pipe
-
-A sling pipe is essentially a sling resource stream, encapsulating a
well-known sling operation
-
-- it provides an output as a sling resource iterator,
-- it gets its input either from a configured path, either from former pipe's
output,
-- each pipe can have scripted configuration, accessing bindings from others
-
-Important bits of a pipe are:
-
-- its type, specifying what sling block you will use, through a RT property,
or a method depending on what [builder you
use](/documentation/bundles/sling-pipes/execution-monitoring.html),
-- its `name`, used in logs, JCR persistence, and bindings,
-- its input, forced with `path` property, or because the pipe follows another
one,
-- its optional expression, configured with `expr` property, that means
different things depending on the pipe,
-- its configuration node, configured with `conf` node, that means different
things depending on the pipe
-
-
+<iframe width="560" height="415"
src="https://www.youtube.com/embed/LhxVE-56p2Y?start=122"; frameborder="0"
allow="autoplay; encrypted-media" allowfullscreen></iframe>
## Get Started
-You can [configure and execute a pipe with java, groovy console, http, or
jmx](/documentation/bundles/sling-pipes/execution-monitoring.html)
+You can either use it with [adobe's
scripts](https://github.com/adobe/adobe-dx/blob/master/apps/scripts) or just
[configure and execute a pipe with java, groovy console, http, or
jmx](/documentation/bundles/sling-pipes/execution-monitoring.html)
To get more familiar with pipes go through the 3 families of pipes to consider
and the samples detailed:
diff --git
a/src/main/jbake/content/documentation/bundles/sling-pipes/bindings.md
b/src/main/jbake/content/documentation/bundles/sling-pipes/bindings.md
index 87149e6..f445cbb 100644
--- a/src/main/jbake/content/documentation/bundles/sling-pipes/bindings.md
+++ b/src/main/jbake/content/documentation/bundles/sling-pipes/bindings.md
@@ -28,9 +28,7 @@ name of "one", "two", ... depending on its position in the
pipe, you can overrid
so following pipe
- .echo('/content/foo')
- .children('nt:unstructured').name('example')
- .write('jcr:description','this node property prop = ${example.prop}')
+ echo /content/foo | children nt:unstructured @ name example | write
jcr:description='this node property prop = ${example.prop}'
with following `/content/foo` tree
@@ -91,4 +89,7 @@ in the JCR, and mentions the path in the [additionalScripts
MV property](/docume
in case a pipe references, or contain another pipe, same binding space will be
used
-
+## Context Aware configuration
+
+there is the possibility to use [context aware
configurations](https://sling.apache.org/documentation/bundles/context-aware-configuration/context-aware-configuration.html)
+ in the bindings like the following: `caconfig.pipeName.bucket.property` where
`pipeName` is a pipe name, bucket & property typical ca configuration accessors.
\ No newline at end of file
diff --git
a/src/main/jbake/content/documentation/bundles/sling-pipes/execution-monitoring.md
b/src/main/jbake/content/documentation/bundles/sling-pipes/execution-monitoring.md
index 01ff957..30c8712 100644
---
a/src/main/jbake/content/documentation/bundles/sling-pipes/execution-monitoring.md
+++
b/src/main/jbake/content/documentation/bundles/sling-pipes/execution-monitoring.md
@@ -18,9 +18,9 @@ A pipe configuration is ultimately a jcr node, with
properties (varying a lot de
| Configuration child node | Explanation |
|---|---|
-| `conf` | optional, contains addition configuration of the pipe (depending on
the type) |
+| `conf` | optional, contains addition configuration of the pipe (depending on
the type) |
| `additionalBinding` | set "global"
[bindings](/documentation/bundles/sling-pipes/bindings.html) (property=value)
in pipe execution |
-| `writer` | set a writer with key / value property being label, and value of
each added entry. Those values can be
[expressions](/documentation/bundles/sling-pipes/bindings.html) |
+| `writer` | set a writer with key / value property being label, and value of
each added entry. Those values can be
[expressions](/documentation/bundles/sling-pipes/bindings.html) |
### Java
@@ -115,14 +115,13 @@ If the pipe already exists in your repository you can run
it following up below
| request path | path of a pipe configuration resource (see above), or a
resource of type `slingPipes/plumber` with a path parameter indicating the pipe
configuration resource path.|
| request method | `GET` or `POST`. Note that `GET` will not work on pipe
modifying content (unless you are using a `dryRun`) |
| request extension | `.json` or `.csv` |
-| request selectors | you can add `status` to get status on a currently
executed pipe|
-
+| request selectors | you can add `status` to get status on a currently
executed pipe|
##### Pipe HTTP Request parameter
| request parameter | Explanation |
|---|---|
-| `size` | size of the returned excerpt. Default response is truncated to 10
items, if you need more (or less), you can modify that settings with the size
parameter. 0 value will return all the items |
+| `size` | size of the returned excerpt. Default response is truncated to 10
items, if you need more (or less), you can modify that settings with the size
parameter. 0 value will return all the items |
| `binding` | json object of global bindings you want to add for the execution
of the pipe e.g. `{testBinding:'foo'}` |
| `writer` | you can configure output of your servlet, with `writer`
parameter, a json object as a pattern to the result you want to have. The
values of the json object are expressions and can reuse each pipe's subpipe
binding. This will be entries of your json output, or headers and values of
your csv output, e.g `{"user":"${user.fullName}"}` |
| `dryRun=true` | if parameter dryRun is set to true, and the executed pipe is
supposed to modify content, it will log (at best it can) the change it *would*
have done, without doing anything |
diff --git
a/src/main/jbake/content/documentation/bundles/sling-pipes/logical.md
b/src/main/jbake/content/documentation/bundles/sling-pipes/logical.md
index bf22833..ffd9c55 100644
--- a/src/main/jbake/content/documentation/bundles/sling-pipes/logical.md
+++ b/src/main/jbake/content/documentation/bundles/sling-pipes/logical.md
@@ -7,24 +7,51 @@ Those pipes help assembling pipes, or modifying the resource
streams
[readers](/documentation/bundles/sling-pipes/readers.html) or
[writers](/documentation/bundles/sling-pipes/writers.html)
could create.
+### FilterPipe (`grep(conf)`)
+outputs the input resource if its matches its configuration
+
+ echo /content/foo | grep foo=bar integerProp=2 booleanOne=false
+
+will outputs `/content/foo` only if it has properties specified, you can
revert the logic with ̀ slingPipesFilter_not` set to true
+
+ echo /content/foo | grep foo=bar @ with slingPipesFilter_not=true
+
+will either return `/content/foo` either nothing depending on it not
containing `@foo=bar`
+
+you can do more complex use case tackling direclty the "compiled" persistence
of the pipe
+
+- `sling:resourceType` is `slingPipes/filter`
+- `conf` node tree that will be tested against the current input of the pipe,
each `/conf/sub@prop=value` will triggers a test
+on `./sub@prop` property of the current input, testing if its value matches
`value` regex. If the special `slingPipesFilter_noChildren=${true}`
+property is there with the value instantiated as a true boolean, then filter
will pass if corresponding node has no children.
+- `slingPipesFilter_test='${...}'` evaluates the property value, and filters
out the stream if the expression is not a boolean or false
+- `slingPipesFilter_not='true'` inverts the expected result of the filter
### Super pipes
-Pipes that litterally contains sub pipes
+Pipes that litterally contains sub pipes, each super pipe share bindings with
each others so data can be passed from one to another
-#### Container Pipe
-assemble a simple sequence of pipes
+#### ReferencePipe (`ref <path>`)
+executes the pipe whose persistence is referenced in path property
-- `sling:resourceType` is `slingPipes/container`
-- `conf` node contains child pipes' configurations, that will be configured in
the order they are found (note you should use sling:OrderedFolder)
+ ref /conf/pipes/aPipePersistence
-Note that pipe builder api automatically creates one for you to chain the
subpipe you are configuring.
+will execute the pipe `/conf/myPipes/aPipePersistence`
+if you add `/conf/myPipes` to plumberImpl `referencePaths` configuration, you
can then execute
-#### ReferencePipe (`ref(path)`)
-executes the pipe referenced in path property
+ ref aPipePersistence
-- `sling:resourceType` is `slingPipes/reference`
+### NotPipe
+executes the pipe referenced in path property, passes input only if referenced
pipe doesn't return any resource
+
+- `sling:resourceType` is `slingPipes/not`
- `path` path of the referenced pipe
+ not /conf/pipes/aPipePersistence
+
+or as for referenced pipe:
+
+ not aPipePersistence
+
#### Manifold
allows parallel execution of the sub pipes listed in configuration
@@ -37,30 +64,10 @@ allows parallel execution of the sub pipes listed in
configuration
whereas a container pipe chains sub pipes and will stop when any subpipe
produces no output, the manifold pipe handles subpipes as independent streams
and combines their output regardless of any void subpipe output
- `executionTimeout` execution time out for each sub pipe; given in seconds;
default is 24h
-### FilterPipe (`grep(conf)`)
-outputs the input resource if its matches its configuration
-
-- `sling:resourceType` is `slingPipes/filter`
-- `conf` node tree that will be tested against the current input of the pipe,
each `/conf/sub@prop=value` will triggers a test
-on `./sub@prop` property of the current input, testing if its value matches
`value` regex. If the special `slingPipesFilter_noChildren=${true}`
-property is there with the value instantiated as a true boolean, then filter
will pass if corresponding node has no children.
-- `slingPipesFilter_test='${...}'` evaluates the property value, and filters
out the stream if the expression is not a boolean or false
-- `slingPipesFilter_not='true'` inverts the expected result of the filter
-
-
-as an example,
-
- echo('/content/foo').grep('foo','bar','slingPipesFilter_not',true).run()
-
-will either return `/content/foo` either nothing depending on it
-not containing `@foo=bar`
-
- echo('content/foo').name('FOO').grep('slingPipesFilter_test','${FOO.foo ==
"bar"}').run()
-
-is an equivalent
+#### Container Pipe
+assemble a simple sequence of pipes
-### NotPipe
-executes the pipe referenced in path property, passes input only if referenced
pipe doesn't return any resource
+- `sling:resourceType` is `slingPipes/container`
+- `conf` node contains child pipes' configurations, that will be configured in
the order they are found (note you should use sling:OrderedFolder)
-- `sling:resourceType` is `slingPipes/not`
-- `path` path of the referenced pipe
+Note that pipe builder api automatically creates one for you to chain the
subpipe you are configuring.
\ No newline at end of file
diff --git
a/src/main/jbake/content/documentation/bundles/sling-pipes/readers.md
b/src/main/jbake/content/documentation/bundles/sling-pipes/readers.md
index 3785658..acd2599 100644
--- a/src/main/jbake/content/documentation/bundles/sling-pipes/readers.md
+++ b/src/main/jbake/content/documentation/bundles/sling-pipes/readers.md
@@ -5,97 +5,72 @@ tags=pipes,slingquery
~~~~~~
those are pipes that will spit out resources, without modifying them. They are
usually combined with
[logical](/documentation/bundles/sling-pipes/logical.html)
-and/or [write](/documentation/bundles/sling-pipes/writers.html) pipes
+and/or [writer](/documentation/bundles/sling-pipes/writers.html) pipes
-### Base pipe (`echo(path)`)
+### Base pipe (`echo <path>`)
outputs what is in input (so what is configured in path).
-- `sling:resourceType` is `slingPipes/base`
+It's handy to set the input of a given sequence in a talkative manner:
-It's handy to set the input
-of a given sequence in a talkative manner:
-
- echo('/content/foo')
- .write('bar',true)
+ echo /content | write foo=bar
-is easier to read, more obvious also than
-
- write('bar',true).with('path','/content/foo')
-
-### XPathPipe (`xpath(expr)`)
-retrieve resources resulting of an xpath query
-
-- `sling:resourceType` is `slingPipes/xpath`
-- `expr` should be a valid xpath query
+You can also pipe it with relative path to go to a children:
-
xpath('/jcr:root/content/foo//element(*,nt:unstructured)[@sling:resourceType="foo/bar"]')
- .write('foo','bar')
+ echo /content | $ some/parent | echo child/path | ...
+
+### XPath Pipe (`xpath <xpath query>`)
-### TraversePipe (`traverse()`)
+ xpath
/jcr:root/content/foo//element(*,nt:unstructured)[@sling:resourceType="foo/bar"]
| write foo=bar
+
+### Traverse Pipe (`traverse`)
traverse current input resource's tree, outputing, as resources, either the
node of the tree, either its properties
-- `sling:resourceType` is `slingPipes/traverse`,
- `breadthFirst` the tree visit will be done deep first, unless this flag is
set to true,
- `depth` max depth the visit should go to,
- `properties` is a flag mentioning the pipe should traverse node's property,
- `nameGlobs` filters the property that should get outputed
-### MultiPropertyPipe
-iterates through values of input multi value property and write them to
bindings
+ echo /content | traverse @ with breadFirst=true depth=10
properties=true | ...
-- `sling:resourceType` is `slingPipes/multiProperty`
-- `path` should be the path of a mv property (if no input)
+### MultiProperty Pipe (`mp`)
+iterates through values of input multi value property and write them to
bindings
+ echo /content/my/months | mp @ name currentMonth | echo
/content/year/${currentMonth} | write visited=true
+
## Sling Query Pipes
Sling Query shares with Sling Pipes the same objective to write more concise
(and efficient) code for
-most common operations.
-Below are the most common [Sling
Query](/documentation/bundles/sling-query.html) methods as reader pipes.
-
-### Find Pipe (`$(expr)`)
-executes
[find](/documentation/bundles/sling-query/methods.html#findselector)(expression)
that searches through the subtree below the current input resource
+most common operations. Below are the most common [Sling
Query](/documentation/bundles/sling-query.html) methods as reader pipes.
-- `sling:resourceType` is `slingPipes/find`
-- `expr` mandatory property, contains Sling Query [selector
string](/documentation/bundles/sling-query/selectors.html)
+### Find Pipe (`$ <expr>`)
+executes
[find](/documentation/bundles/sling-query/methods.html#findselector)(expression)
that searches through the subtree below the current input resource.
+Typical handy usage would be to use resource type selector like that:
- echo("/content/foo")
- .$("nt:unstructured[sling:resourceType=foo/bar]")
- .write('foo','bar')
+ echo /content | $ foo/bar
-### Children Pipe (`children(expr)`)
+### Children Pipe (`children <expr>`)
executes
[children](/documentation/bundles/sling-query/methods.html#childrenselector)(expression)
that searches through the immediate children of the current input resource)
-- `sling:resourceType` is `slingPipes/children`
-- `expr` mandatory property, contains Sling Query [selector
string](/documentation/bundles/sling-query/selectors.html)
+ echo /content/some/container | children foo/bar
-### Siblings Pipe (`siblings(expr)`)
+### Siblings Pipe (`siblings <expr>`)
executes
[siblings](/documentation/bundles/sling-query/methods.html#siblings-selector-)(expression)
that searches through siblings of current input resource
-- `sling:resourceType` is `slingPipes/slingQuery`
-- `expr` mandatory property, contains Sling Query [selector
string](/documentation/bundles/sling-query/selectors.html)
+ echo /content | siblings foo/bar
-### Parent Pipe (`parent()`)
+### Parent Pipe (`parent <expr>`)
executes [parent](/documentation/bundles/sling-query/methods.html#parent-)()
that retrieves current parent
-- `sling:resourceType` is `slingPipes/parent`
-
-### Closest Pipe (`closest(expr)`)
+### Closest Pipe (`closest <expr>`)
executes
[closest](/documentation/bundles/sling-query/methods.html#closest-selector-)(expression)
that searches the closest parent resource of current input resource
-- `sling:resourceType` is `slingPipes/slingQuery`
-- `expr` mandatory property, contains Sling Query [selector
string](/documentation/bundles/sling-query/selectors.html)
-
- .$("nt:unstructured[sling:resourceType=foo/bar]")
- .closest('jcr:content')
+ echo /content | $ foo/bar | closest jcr:content
will find `jcr:content` nodes that have `foo/bar` typed resource somewhere in
their tree
-### Parents Pipe (`parents(expr)`)
+### Parents Pipe (`parents <expr>`)
executes
[parents](/documentation/bundles/sling-query/methods.html#parents-selector-)(expression)
that searches all the parents of the current input resource
-- `sling:resourceType` is `slingPipes/slingQuery`
-- `expr` mandatory property, contains Sling Query [selector
string](/documentation/bundles/sling-query/selectors.html)
-
## InputStream reader pipes
those are specific reader pipes, that read information an input stream from
defined in expr configuration,
@@ -106,47 +81,38 @@ that can be:
- a file passed as request parameter with `pipes_inputFile` as parameter name
(in that case, expr can be empty)
- direct data stream in the expression
-### JsonPipe (`json(expr)`)
+### Json Pipe (`json expr`)
feeds bindings with json stream
-
-- `sling:resourceType` is `slingPipes/json`
-- `expr` see above
-- `valuePath` json path like expression that defines where the json value we
care about is. E.g. `$.items[2]` considers root is an object and that we want
the 3rd item of items array, located at `items` key of the root object.
+`valuePath` is a property as a json path like expression that defines where
the json value we care about is. E.g. `$.items[2]` considers root is an object
and that we want the 3rd item of items array, located at `items` key of the
root object.
In case the json value is an array, the pipe will loop over the array
elements, and output each one in the binding.
Output resource remains each time the input one.
-
.json('{items:[{val:1},{val:2},{val:3}]}').with('valuePath','$.items').name('demo')
- .mkdir('/content/${demo.val}')
+ json {"items":[{"val":"1"},{"val":"2"},{"val":"3"}]} @ with
valuePath=$.items @ name demo | mkdir /content/${demo.val}
-should create a tree of 3 resources /content/1, /content/2 and /content/3.
+will create a tree of 3 resources /content/1, /content/2 and /content/3.
An interesting usage of the JSON pipe can also be to loop over an array of
Strings like
-
.json('["/content/mySite/page1","/content/mySite/page2","/content/mySite/page3"]')
- .echo('${one}')
- .children("jcr:content")
- .write("update","something")
+ json
["/content/mySite/page1","/content/mySite/page2","/content/mySite/page3"]
+ | echo ${one}
+ | echo jcr:content
+ | write update=something
-### CsvPipe (`csv(expr)`)
+### Csv Pipe (`csv <expr>`)
feeds bindings with csv stream
-- `sling:resourceType` is `slingPipes/csv`
-- `expr` see above
-- `separator` separator character, default being comma `,`
-
- .csv('idx,val\n1,1\n2,2\n3,3').name('demo')
- .mkdir('/content/${demo.val}')
+ csv idx,val\\n1,1\n2,2\\n3,3 @ name demo
+ | mkdir /content/${demo.val}
-should create a tree of 3 resources /content/1, /content/2 and /content/3
+should create a tree of 3 resources /content/1, /content/2 and /content/3. You
can change separator with `separator` property
-### Regexp pipe (`egrep(expr)`)
-feeds bindings with text input stream, parsed with a regexp
+ csv a;b @ with separator=;
-- `sling:resourceType` is `slingPipes/egrep`
-- `expr` see above
-- `pattern` is a regular expression, with named group (e.g. `(?<user>.*)`)
that will be used to produce the output binding names
+### Regexp pipe (`egrep <expr>`)
+feeds bindings with text input stream, parsed with a regexp `pattern`, that is
a regular expression, with named
+group (e.g. `(?<user>.*)`) that will be used to produce the output binding
names
- egrep("https://sling.apache.org/";)
-
.with("pattern",'src=\"/res/(?<asset>/[\\-\\w\\.\\/0-9]+)\"').name("demo")
- .echo('/content/assets/${demo.asset}')
+ egrep http://some.site.com @ pattern=/res/(?<asset>/[\-\w\.\/0-9]+) @
name demo
+ | echo /content/assets
+ | write test=demo.asset
diff --git
a/src/main/jbake/content/documentation/bundles/sling-pipes/samples.md
b/src/main/jbake/content/documentation/bundles/sling-pipes/samples.md
index 9bf826b..091148a 100644
--- a/src/main/jbake/content/documentation/bundles/sling-pipes/samples.md
+++ b/src/main/jbake/content/documentation/bundles/sling-pipes/samples.md
@@ -8,7 +8,7 @@ tags=pipes
those are samples built with pipebuilder api you can
-### echo | $ | children | write
+### echo | $ | children | write
write repository user prefix Ms/Mr depending on gender
echo('/home/users')
diff --git
a/src/main/jbake/content/documentation/bundles/sling-pipes/writers.md
b/src/main/jbake/content/documentation/bundles/sling-pipes/writers.md
index 52bd72a..fa10170 100644
--- a/src/main/jbake/content/documentation/bundles/sling-pipes/writers.md
+++ b/src/main/jbake/content/documentation/bundles/sling-pipes/writers.md
@@ -7,87 +7,73 @@ tags=pipes
those pipes all are using common sling (or other) APIs to modify content.
You'll probably need some
[reader](/documentation/bundles/sling-pipes/readers.html)
pipes and/or [logical](/documentation/bundles/sling-pipes/logical.html) pipes
first to put you into the right context.
-##### Write Pipe (`write(conf)`)
+##### Write Pipe (`write <...>`)
writes given nodes and properties to current input resource
+
+ echo /content/foo | write foo1=bar1 foo2=2 foo3=true foo4=one.old
foo5=timeutil.of('2018-05-05T11:50:55+02:00')
+
+will write `@foo1='bar1'`, `@foo2=2`, `@foo3=true`,
[`@foo4=${one.old}`](/documentation/bundles/sling-pipes/bindings.html),
+ and @foo5 being a Date property in `/content/foo`.
+
+Another handy usage is to copy whole tree sections, using the expr
configuration
+ echo /content/foo | write @ expr /content/tree/to/copy
+
+Finally, for more complicated cases where you need a structure to be written,
you can use JCR / Resource explorer to edit the
+"compiled" persistence of the pipe, and create the given structured under conf.
- `sling:resourceType` is `slingPipes/write`
-- `conf` node tree that will be copied to the current input of the pipe, each
property's names and value will be written to the input resource. Input
resource will be outputed. Note that properties that will be evaluated (in an
expression) as `null` for a given input resource will be removed from it. E.g.
`./conf/some/node@prop=${null}` will add `./conf/some/node` structure if not in
current input resource, but remove its `prop` property if any).
-- `expr` used if no configuration node provided: path of a content tree this
will write to the current destination (basically a deep copy)
+- `conf` node tree that will be copied to the current input of the pipe, each
property's names and value will be written to the input resource. Input
resource will be outputed. Note that properties that will be evaluated (in an
expression) as `null` for a given input resource will be removed from it. E.g.
`./conf/some/node@prop=${null}` will add `./conf/some/node` structure if not in
current input resource, but remove its `prop` property if any).
-For most of the case where you just need to write properties, pipe builder API
allows you to
-e.g.
-
- .echo('/content/foo')
- .write('foo1','bar1','foo2','bar2')
-
-will write `@foo1=bar1` and `@foo2=bar2` in `/content/foo`. For more
complicated cases where you need a structure to be written,
-just use a JCR / Resource explorer to edit the persistence of the pipe, and
create the given structured under conf.
Note that you can use expressions in that node tree, and specifically, for a
node name, parent of a tree you want to
be conditionally written, use `$if${...}nodename` syntax, that will basically
only create such tree if the expression is true.
-
-Note that using `expr` you need configuration node _not_ to be here, and
`write` shortcut creates one systematically.
-So if you want to use pipe builder and that, you'd need something like
-
- .echo('/content/destination')
- .pipe("slingPipes/write").expr("/content/source")
-
-##### MovePipe (`mv(expr)`)
+##### MovePipe (`mv <expr>`)
JCR move of current input to target path (can be a node or a property)
-- `sling:resourceType` is `slingPipes/mv`
-- `expr` full target path, note that parent path must exists
-
- .echo("/content/foo/old/location")
- .mv("/content/bar/new/location")
+ echo /content/foo/old/location | mv /content/bar/new/location
following will move resource at `/content/foo/old/oldlocation` to under
`/content/bar/new` before `newlocation`
- .echo("/content/foo/old/oldlocation")
- .mv("/content/bar/new/newlocation").with('orderBeforeTarget', true)
+ echo /content/foo/old/oldlocation | mv /content/bar/new/newlocation @
with orderBeforeTarget=true
following will move resource at `/content/foo/old/oldlocation` to
`/content/bar/new/newlocation` and overwrite `newlocation`
- .echo("/content/foo/old/oldlocation")
- .mv("/content/bar/new/newlocation").with('overwriteTarget', true)
+ echo /content/foo/old/oldlocation | mv /content/bar/new/newlocation @
with overwriteTarget=true
+
+##### RemovePipe (`rm`)
+removes the input resource, returns the parent, regardless of the resource
being a node,
+ echo /content/foo/nodeToRemove | rm
-##### RemovePipe (`rm()`)
-removes the input resource, returns the parent, regardless of the resource
being a node, or
-a property
+or a property
+
+ echo /content/foo/node/propertyToRemove | rm
+for more complex use cases, where you need to remove several resources in a
row, at different level of a subtree,
+you can use the "compiled" persistence, where
- `sling:resourceType` is `slingPipes/rm`
- `conf` node tree that will be used to filter relative properties & subtrees
to the current resource to remove.
A subnode is considered to be removed if it has no property configured, nore
any child.
-more common usage is just without configuration node, removing incoming
resource
+##### PathPipe (`mkdir <expr>`)
+get or create path given in expression. Uses
[ResourceUtil.getOrCreateResource](https://sling.apache.org/apidocs/sling8/org/apache/sling/api/resource/ResourceUtil.html#getOrCreateResource-org.apache.sling.api.resource.ResourceResolver-java.lang.String-java.lang.String-java.lang.String-boolean-)
- .echo("/content/foo/toRemove")
- .rm()
+ mkdir /content/folders/to/create
-##### PathPipe (`mkdir(expr)`)
-get or create path given in expression. Uses
[ResourceUtil.getOrCreateResource](https://sling.apache.org/apidocs/sling8/org/apache/sling/api/resource/ResourceUtil.html#getOrCreateResource-org.apache.sling.api.resource.ResourceResolver-java.lang.String-java.lang.String-java.lang.String-boolean-)
+will create a `/content/folders/to/create` path of `sling:Folder` nodes
-- `sling:resourceType` is `slingPipes/path`
-- `nodeType` node type of the intermediate nodes to create
-- `autosave` should save at each creation (will make things slow, but
sometimes you don't have choice)
+ echo /content/folders/to/create | mkdir childWithDifferentType @ with
nodeType=nt:unstructured
- .mkdir("/content/foo/bar")
-
-will create a `/content/foo/bar` path of `sling:Folder` nodes
+will create a child with `nt:unstructured` node type.
-##### PackagePipe (`pkg(expr)`)
+##### PackagePipe (`pkg <expr>`)
will create a package and add current resource as a filter. At the end of
super pipe execution, will attempt to build the package
-- `sling:resourceType` is `slingPipes/package`
-- `expr` package path
This example searches for folders in a given location and package them up
- .echo("/content/foo/bar")
- .$("sling:Folder")
- .pkg("/etc/packages/foobar-folders.zip")
+ echo /content/foo/bar | $ sling:Folder | pkg
/etc/packages/foobar-folders.zip
-##### AuthorizablePipe (`auth(conf)`)
+##### AuthorizablePipe (`auth (conf)`)
retrieve authorizable resource corresponding to the id passed in expression,
or if not found (or void expression),
from the input path, output the found authorizable's resource
caution this pipe **can modify content** in case additional configuration is
added (see below)
@@ -126,8 +112,7 @@ passed as the expression
following will give bar-users authorizable the aggregate privilege (jcr:all)
on /content/foo/bar
- .echo("/content/foo/bar")
- .allow("bar-users")
+ echo /content/foo/bar | allow bar-users
following will give bar-users authorizable the specific rights to read|write
on /content/foo/bar
@@ -136,5 +121,4 @@ following will give bar-users authorizable the specific
rights to read|write on
and following will deny bar-users authorizable to read on /content/foo/bar
- .echo("/content/foo/bar")
- .deny("bar-users")
\ No newline at end of file
+ echo /content/foo/bar | deny bar-users
\ No newline at end of file
