Multiline local variable

[Jolanrensen]

Hi!

I was wondering whether it would/could be possible to define a //#local variable using a multiline string.
I want to use JCP to reuse documentation for many function overloads and while I can define the documentation in gradle, I think it would be better to define them in the same file they are reused.
This is already possible:

//#local ADD = " * Original [DataFrame] is not modified.\n *\n * @throws [DuplicateColumnNamesException] if columns in expected result have repeated names\n * @throws [UnequalColumnSizesException] if columns in expected result have different sizes\n * @return new [DataFrame] with added columns"

/**
 * Creates new [DataFrame] with given columns added to the end of original [DataFrame.columns] list.
 *
/*$ADD$*/
 * @param columns columns to add
 */
public fun <T> DataFrame<T>.add(vararg columns: AnyBaseCol): DataFrame<T> = addAll(columns.asIterable())

But you can imagine that writing long documentation on the same line would be a hassle. Is there a notation possible with JCP that allows for something like this?

//#local ADD = """ * Original [DataFrame] is not modified.
//# *
//# * @throws [DuplicateColumnNamesException] if columns in expected result have repeated names
//# * @throws [UnequalColumnSizesException] if columns in expected result have different sizes
//# * @return new [DataFrame] with added columns"""

[raydac]

may be it would be easy just to load multiline file with evalfile() function?

[Jolanrensen]

That works too! Thanks!
But I do like having the documentation in the same file so I can check that references to other classes work. (Also helps with refactoring)
For example:

import org.jetbrains.kotlinx.dataframe.DataFrame
import org.jetbrains.kotlinx.dataframe.exceptions.DuplicateColumnNamesException
import org.jetbrains.kotlinx.dataframe.exceptions.UnequalColumnSizesException


/**
//#local ADD0 = " * Original [DataFrame] is not modified."
//#local ADD1 = " *"
//#local ADD2 = " * @throws [DuplicateColumnNamesException] if columns in expected result have repeated names"
//#local ADD3 = " * @throws [UnequalColumnSizesException] if columns in expected result have different sizes"
//#local ADD4 = " * @return new [DataFrame] with added columns"
//
//#local ADD = ADD0 + "\n" + ADD1 + "\n" + ADD2 + "\n" + ADD3 + "\n" + ADD4
 */


/**
 * Creates new [DataFrame] with given columns added to the end of original [DataFrame.columns] list.
 *
/*$ADD$*/
 * @param columns columns to add
 */
public fun <T> DataFrame<T>.add(vararg columns: AnyBaseCol): DataFrame<T> = addAll(columns.asIterable())

If I don't link to, for instance, UnequalColumnSizesException from a documentation part, the linter will remove it from the imports, breaking the link when it gets pasted at the other methods.

For this, a multiline string would be ideal, unless you know another way to achieve what I want in an easy-to-use manner :)

[Jolanrensen]

I'll probably go another route for my particular issue, but I do think that, aside from multi-line strings, also multi-line statements could be a great addition to JCP.

Like

//#local VAR = "a" +
//# "test"

Just my 2 cents

[raydac]

the preprocesser was developed to process line by line, not any char stream, so that there should be different approach, may be some function or directive which will be filling some variable by following block of strings

[raydac]

since 7.3.0 added special variables

• jcp.text.buffer.all
• jcp.text.buffer.middle
• jcp.text.buffer.prefix
• jcp.text.buffer.postfix

they provide access to internal text buffers of preprocessor so they allow make trick and get a multiline text into a local variable for instance

//#prefix+
some multiline
text to be placed
into a local variable
//#prefix-
//#local multiline_text = jcp.text.buffer.prefix
//#local jcp.text.buffer.prefix=""
Multiline text:
/*$multiline_text$*/