Newbie questions about the declarative syntax

[Anton Shepelev]

Hello, all

From some examples in the internet I have found that a
mulitline Windows batch script in Jenkins may be called with
this step:

bat """
chcp 1251
c:\path\to\program.exe
"""

Where is this syntax documented with regard to:

1. the backslash escapes, and
2. the triple quoataion marks?

Accoring to the steps reference, the `bat' step can take
many parateters, the first being `script'. How I invoke the
`bat' step with several parameters, e.g.: `script' and
`returnStdout'?

Where is the general specification of the declarative
syntax? I am somewhat confused because the documentation
starts from specific examples.

[Gianluca]

Hi Anton,

take into account that the declarative syntax (and in general Jenkins pipelines) are just a DSL (https://en.wikipedia.org/wiki/Domain-specific_language) heavily based on Groovy language (http://groovy-lang.org/index.html).

So, many (really many) things you can do ... it's just Groovy language, like the one you asked.

In fact, triple quote is documented at http://groovy-lang.org/syntax.html#_triple_single_quoted_string

And also many "command" like "bat" you mentioned in the email are just Groovy function and follow the Groovy rules about parameters and how you can call them.

In the case of "bat" is you just pass one parameter is used as script, as you pass more than one you need to specify who is what:

"bat script: "whatever", returnStout: true"

I hope it helps to get you started on learning it.

Cheers,

Gianluca.

[Anton Shepelev]

I wrote:

> bat """
> chcp 1251
> c:\\path\\to\\program.exe
> """

The backslashes should be doubled:

c:\\path\\to\\program.exe

Sorry for the typo.

[Baptiste Mathus]

Backslash escape is because the parser needs to know you're not trying to "despecialize" the following character. By default \ *is* a special character. (E.g. "\to" would mean \t, which is a tabulation, then the letter o).

So using \ because the second \, the parser just 

It's the same in Java, C AFAIR and probably most languages BTW.

Cheers

--
You received this message because you are subscribed to the Google Groups "Jenkins Users" group.
To unsubscribe from this group and stop receiving emails from it, send an email to jenkinsci-use...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/jenkinsci-users/20200814193627.932d3a0cb364bd94765a8d38%40gmail.com.

[Anton Shepelev]

Gianluca:

> take into account that the declarative syntax (and in general
> Jenkins pipelines) are just a DSL
> ( https://en.wikipedia.org/wiki/Domain-specific_language )
> heavily based on Groovy language
> ( http://groovy-lang.org/index.html ).
> So, many (really many) things you can do ... it's just Groovy
> language, like the one you asked.

Thank you. I know about domain-specific languages, having
programmed in Simula, GPSS, and Prolog, but I wonder why the
Jenkins documentation references that Wikipedia page about DSL's,
which does even mention Groovy, yet fails to reference a document
describing the syntax of Groovy:

https://www.jenkins.io/doc/book/pipeline/#pipeline-syntax-overview

That comfused me! If possible, will the maintaners please consider
informing the readers that the declarative syntax is based on
Groovy and direct them to the Groovy specification?

> In fact, triple quote is documented at
> http://groovy-lang.org/syntax.html#_triple_single_quoted_string
> And also many "command" like "bat" you mentioned in the email are
> just Groovy function and follow the Groovy rules about parameters
> and how you can call them.
> In the case of "bat" is you just pass one parameter is used as
> script, as you pass more than one you need to specify who is what:
> "bat script: "whatever", returnStout: true"

Thank you.

--
() ascii ribbon campaign - against html e-mail
/\ http://preview.tinyurl.com/qcy6mjc [archived]

[Anton Shepelev]

Baptiste Mathus:

> Backslash escape is because the parser needs to know you're not
> trying to "despecialize" the following character. By default \
> *is* a special character. (E.g. "\to" would mean \t, which is a
> tabulation, then the letter o).
> So using \ because the second \, the parser just
>
> It's the same in Java, C AFAIR and probably most languages BTW.

I know about the purpose of escape characters, but -- until
Gianluca's reply -- I didn't know where to look for their exact
specification in the declarative syntax.

[Mark Waite]

On Sat, Aug 15, 2020 at 3:42 PM Anton Shepelev <anto...@gmail.com> wrote:

Gianluca:

> take into account that the declarative syntax (and in general
> Jenkins pipelines) are just a DSL
> ( https://en.wikipedia.org/wiki/Domain-specific_language )
> heavily based on Groovy language
> ( http://groovy-lang.org/index.html ).
> So, many (really many) things you can do ... it's just Groovy
> language, like the one you asked.

Thank you. I know about domain-specific languages, having
programmed in Simula, GPSS, and Prolog, but I wonder why the
Jenkins documentation references that Wikipedia page about DSL's,
which does even mention Groovy, yet fails to reference a document
describing the syntax of Groovy:

  https://www.jenkins.io/doc/book/pipeline/#pipeline-syntax-overview

That comfused me! If possible, will the maintaners please consider
informing the readers that the declarative syntax is based on
Groovy and direct them to the Groovy specification?

Thanks for the suggestion.  We've had many users that expected
Jenkins Pipeline to be Groovy (especially scripted Pipeline
users) instead of being a domain specific language that is based
on Groovy.  I fear that linking to more details of Groovy syntax
will tend to confuse those users even more rather than clarify
for them.

The syntax of Declarative Pipeline is quite specific to Jenkins.
Linking from Declarative Pipeline documentation to the Groovy
syntax seems to me like it will be more likely to confuse users
rather than clarify for them.  Declarative Pipeline is well
suited for use in the Blue Ocean pipeline editor and in defining
Pipelines with Jenkins.

I'd rather include specific descriptions of syntax rules for
single quote and double quote strings and for variable expansion
rather than link to the Groovy documentation.

Mark Waite

 

> In fact, triple quote is documented at
> http://groovy-lang.org/syntax.html#_triple_single_quoted_string
> And also many "command" like "bat" you mentioned in the email are
> just Groovy function and follow the Groovy rules about parameters
> and how you can call them.
> In the case of "bat" is you just pass one parameter is used as
> script, as you pass more than one you need to specify who is what:
> "bat script: "whatever", returnStout: true"

Thank you.

--
()  ascii ribbon campaign - against html e-mail
/\  http://preview.tinyurl.com/qcy6mjc [archived]

--
You received this message because you are subscribed to the Google Groups "Jenkins Users" group.
To unsubscribe from this group and stop receiving emails from it, send an email to jenkinsci-use...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/jenkinsci-users/20200816004151.e46885ae9c38872a3d92d65d%40gmail.com.

[Anton Shepelev]

Mark Waite:

> We've had many users that expected Jenkins Pipeline to be Groovy
> (especially scripted Pipeline users) instead of being a domain
> specific language that is based on Groovy. I fear that linking
> to more details of Groovy syntax will tend to confuse those users
> even more rather than clarify for them.

If the declarative syntax of Jenkins is not a strict sub- or
superset of Groovy, and if the differences are not easy to list,
then I agree.

> The syntax of Declarative Pipeline is quite specific to Jenkins.
> Linking from Declarative Pipeline documentation to the Groovy
> syntax seems to me like it will be more likely to confuse users
> rather than clarify for them. Declarative Pipeline is well
> suited for use in the Blue Ocean pipeline editor and in defining
> Pipelines with Jenkins.

Then my question remains: where can I find the specification, or at
least a reasonably detailed descriptionp[1], of the Jenkins
declarative syntax? The only description that I have been able to
locate is:

https://www.jenkins.io/doc/book/pipeline/#declarative-pipeline-fundamentals ,

but instead of specifying or describing the syntax, it gives a
small example and calls it a day. If Jenkins users ought not to
study the declarative syntax from the Groovy documenation, Jenkins
should provide its own. And it should be sufficient for writing a
Jenkinsfile without asking here or looking elsewhere.

> I'd rather include specific descriptions of syntax rules for
> single quote and double quote strings and for variable expansion
> rather than link to the Groovy documentation.

That would be great. Has this not come up before? How do users
learn the declarative syntax?

1. With the example of Markdown,
Description: https://daringfireball.net/projects/markdown/syntax
Specification: https://spec.commonmark.org/0.29/

Another good example is the C programming language, specified in
an ISO standard and described in the famous book by K&R.

In the long run, I think both are needed, but I should be happy
with just a more detailed informal description.

[Jérôme Godbout]

There is many things that work in Groovy that doesn't in Pipeline scripting. Also the scripts approval for string manipulation and all those nightmare ish behavior make it trial and error to write something that actually work. Often I end up doing ugly for loop just because foreach and the like behave like crap. I wish it was Groovy with a library addon, but it ain't. The pipeline idea was a great idea. The usage of Groovy ish scripting language was a bad one. This is a pipeline, it will do extensive file manipulation and source operation, they should have chosen a scripting language that can do those thing easily. I understand that the backend is Java and using Groovy as the scripting engine over it was easier by nature, but this is not even full fledge Groovy and the behavior is unpredictable at best. @NonCPS anyone? string regex that need approval...

I rely more and more on Python and Groovy only call a python script now a day. I did try to put more stuff into that pipeline syntax, but it always end up in pain and hard to achieve cross platform scripts.

--
You received this message because you are subscribed to the Google Groups "Jenkins Users" group.
To unsubscribe from this group and stop receiving emails from it, send an email to jenkinsci-use...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/jenkinsci-users/20200816013539.47dad1d2cadf88723ced7b13%40gmail.com.