Proposed CLI Syntax

[drewatk]

Okay, here's how I see someone using this tool through the CLI

Here's a sample project directory structure as an example

project

|-- src
    |-- input1.clv.html
    |-- input2.clv.html
    |-- partials
        |-- button1.clv
        |-- sections
            |-- section1.clv
            |-- section2.clv
            |-- section3.clv
|-- out
    |-- input1.html
    |-- input2.html

Here are a few use cases for the CLI:

cleave src/input1.clv.html Either outputs to stdout (to be piped) or writes input1.html in the current directory. If we have it output to stdout, it's not really consistent with anything else here.

cleave src/input1.clv.html out/index.html OR cleave src/input1.clv.html out/ Writes out the output to out/index.html or out/input1.html`, respectively.

cleave src/ Outputs puts all output in current directory, with the same file names but an .html extension

cleave src/ out/ Every .clv.html file in input is transformed and output with the same name in the output/ directory, as they are above.

cleave src/ output.html This is an error. You can only specify the name of the output if the input is a single file.

A couple of other things:

• ditch the config.json
• I don't think the compiler should not handle multiple source files, the CLI or the API will call each call a render(<cleave html>, <some sort of output or file printer>) function

[vritant24]

1 - The reason we didn't go with custom file extensions is because text editors won't have syntax highlighting. If that's not too big of an issue, we can switch. 2 - "I don't think the compiler should not handle multiple source files, the CLI or the API will call each call a render(<cleave html>, <some sort of output or file printer>) function" What do you mean here?

[drewatk]

1. I Think that .clv.html would still be recognized as html? That could also be the extension for partials. Edit: Tested on VSCode and it works.
2. To the compiler itself, there would be no handling of multiple source files, that functionality would be separated out into the CLI program.

[vritant24]

1. so if even the partials are clv.html how would we know what files need to be put into the output directory? We could restrict them to a certain folder structure and say that all source files need to be in pages directory, but I thought giving a config gives more flexibility to a user. Although a CLI wasn't in my mind then.

2. So how exactly would the CLI compile the multiple source files? Because the same partials could be shared among source files, and if the CLI calls the compiler separately on all of them, we will be re-reading files unless if there is a global structure storing the document trees

[drewatk]

1. What if the partials were .clv.html and the files to be compiled were .html?
2. Valid point, maybe later it could be resolved by caching the partials

[claytn]

1.) I like this. Not too crazy about the double file extension, but I think it's a good way to make a distinction between the two types of "html" users will be writing when using this tool and maintaining the syntax highlighting expected when writing html. I think restricting users to have their cleaves and source pages within specific folders might be too restrictive.

2.) Should be fairly simple to have the compiler return a list of compiled cleaves (.clv.html) that were generated for a single source file and keep appending the newly generated cleaves within a list maintained by the CLI. Each time the compiler is called the CLI would pass this list of cleaves and the compiler will use these as needed.

[vritant24]

what if you have the main pages be .html and the partials be .clv.html? There is a difference created between them, as well as a specific extension for the cleave files