Repository: apple/pkl
File: pkl-cli/src/main/kotlin/org/pkl/cli/commands/FormatterCommand.kt (Kotlin)

Code before:
import com.github.ajalt.clikt.parameters.arguments.argument
import com.github.ajalt.clikt.parameters.arguments.multiple
import com.github.ajalt.clikt.parameters.options.default
import com.github.ajalt.clikt.parameters.options.flag
import com.github.ajalt.clikt.parameters.options.option
import com.github.ajalt.clikt.parameters.types.enum
import com.github.ajalt.clikt.parameters.types.path
import java.nio.file.Path
import org.pkl.cli.CliFormatterCommand
import org.pkl.formatter.GrammarVersion

class FormatterCommand : CliktCommand(name = "format") {
  override fun help(context: Context) =
    """
    Format or check formatting of Pkl files.
    
    Exit codes:
      - 0: All files were properly formatted
      - 1: A non-formatting error ocurred (Ex.: IO error)
      - 11: One or more files had formatting violations
    
    Examples:
    
    ```
    # formats all Pkl files inside `my/folder/` recursively, overwriting then
    pkl format -w my/folder/
    
    # checks the formatting of `foo.pkl`
    # writting to stdout the absolute path of the file if it's not properly formatted
    pkl format --names foo.pkl
    ```
  """
      .trimIndent()

  override fun helpEpilog(context: Context) = "For more information, visit $helpLink"

  val paths: List<Path> by
    argument(name = "paths", help = "Files or directory to check.")
      .path(mustExist = true, canBeDir = true)
      .multiple()

  val grammarVersion: GrammarVersion by
    option(
        names = arrayOf("--grammar-version"),
        help =
          """
          The grammar compatibility version to use.$NEWLINE
          ${GrammarVersion.entries.joinToString("$NEWLINE", prefix = "  ") {
            val default = if (it == GrammarVersion.latest()) " `(default)`" else ""
            "`${it.version}`: ${it.versionSpan}$default"
          }}

Review comment (suggestion):
Our other code blocks use a `$` to show that this is a shell command input (see `pkl project resolve --help`)

```suggestion
    $ pkl format -w my/folder/
```

Code after:
import com.github.ajalt.clikt.parameters.arguments.argument
import com.github.ajalt.clikt.parameters.arguments.multiple
import com.github.ajalt.clikt.parameters.options.default
import com.github.ajalt.clikt.parameters.options.flag
import com.github.ajalt.clikt.parameters.options.option
import com.github.ajalt.clikt.parameters.types.enum
import com.github.ajalt.clikt.parameters.types.path
import java.nio.file.Path
import org.pkl.cli.CliFormatterCommand
import org.pkl.formatter.GrammarVersion

class FormatterCommand : CliktCommand(name = "format") {
  override fun help(context: Context) =
    """
    Format or check formatting of Pkl files.
    
    Examples:
    
    ```
    # Overwrite all Pkl files inside `my/folder/`, recursively.
    $ pkl format -w my/folder/
    
    # Check formatting of all files, printing filenames with formatting violations to stdout.
    # Exit with exit code `11` if formatting violations were found.
    $ pkl format --diff-name-only my/folder/
    
    # Format Pkl code from stdin.
    $ echo "foo = 1" | pkl format -
    ```
  """
      .trimIndent()

  override fun helpEpilog(context: Context) = "For more information, visit $helpLink"

  val paths: List<Path> by
    argument(name = "paths", help = "Files or directory to check. Use `-` to read from stdin.")
      .path(mustExist = false, canBeDir = true)
      .multiple()

  val grammarVersion: GrammarVersion by
    option(
        names = arrayOf("--grammar-version"),
        help =
          """
          The grammar compatibility version to use.$NEWLINE
          ${GrammarVersion.entries.joinToString("$NEWLINE", prefix = "  ") {
            val default = if (it == GrammarVersion.latest()) " `(default)`" else ""
            "`${it.version}`: ${it.versionSpan}$default"
          }}
          """
            .trimIndent(),