Syntax verbosity

[realdadfish]

Hi! I just saw your G+ posting and thought "yes, this is a nice idea", however, when I looked at the syntax I found it overly verbose.

Since Markdown basically describes hierarchical documents, couldn't be your API hierarchical as well, to avoid all the nasty and overly verbose instantiation?

[Steppschuh]

Hey, thanks for input. Could you provide an example usage for what you'd expect?

[realdadfish]

Well, I imagined something along the lines:

new MarkdownBuilder()
    .header1("This is a header")
    .beginParagraph()
        .text("Normal text")
        .bold("This is bold")
        .beginBold()
            .italics("this is bold and italics")
        .endBold()
        .text("more normal text")
    .endParagraph()
    .paragraph("Regular, normal formatted text")
    .toString()

The idea would be to provide a .beginX() and .endX() for cascading elements and an override .x("bla") for single elements. One could also make the API a little leaner and skip all the specific begin / end methods in favour of one general one:

MarkdowBuilder builder = new MarkdownBuilder();
builder.header1("This is a header")
    .begin(builder.paragraph())
        .text("Normal text")
        .bold("This is bold")
        .begin(builder.bold())
            .italics("this is bold and italics")
        .end()
        .text("more normal text")
    .end()
    .paragraph("Regular, normal formatted text")
    .toString()

I'd probably play around with the different syntaxes a bit and would use what feels more natural / the fastest to type. One could also impose some restrictions through this, like adding elements to single elements such as horizontal lines. I'd imagine you need a smarter syntax anyways when it comes to list support, for example.

[Steppschuh]

This sounds like a reasonable idea. I'll look into creating a builder and keep you updated.

[Steppschuh]

I've fiddled around with a builder in this branch. Here's an example, please let me know what you think:

@Test
public void example3() throws Exception {
    MarkdownBuilder builder = new TextBuilder()
            .heading("Markdown Builder")
            .text("Demonstrating: ").bold("Bold Text")
            .newParagraph()
            .quote("I should be a quote\nI should still be a quote")
            .beginQuote()
                    .text("I should be a quote").newLine()
                    .text("I should still be a quote")
            .end()
            .newParagraph()
            .code("INLINE_CODE")
            .beginCodeBlock(CodeBlock.LANGUAGE_JAVA)
                    .text("// some comment").newLine()
                    .text("dummyMethod(this);")
            .end()
            .subHeading("Lists")
            .unorderedList(
                    "I should be an item",
                    italic("I should be an italic item")
            )
            .beginList()
                    .text("I should be an item")
                    .italic("I should be an italic item")
            .end()
            .newParagraph()
            .taskList(
                    task("Task 1", true),
                    task("Task 2", false),
                    task("Task 3")
            );

    System.out.println(builder.toString());
}

This would print:

Markdown Builder

Demonstrating: Bold Text

I should be a quote I should still be a quote

I should be a quote I should still be a quote

INLINE_CODE

// some comment
dummyMethod(this);

Lists

• I should be an item

• I should be an italic item

• I should be an item

• I should be an italic item

• [x] Task 1

• [ ] Task 2

• [ ] Task 3