Package org.moeaframework.util.cli

Class UpdateCodeSamples

java.lang.Object
org.moeaframework.util.cli.CommandLineUtility
org.moeaframework.util.cli.UpdateCodeSamples
public class UpdateCodeSamples extends CommandLineUtility
Utility to update code samples and output found in various documentation files, in particular Markdown, by embedding special instructions within the files that are processed by this utility. These instructions are embedded as comments in the document, allowing the instruction to remain hidden when the document is rendered: 

   <!-- :<processor>: arg1 arg2 ... -->
The processor type, which is surrounded by colons (:), determines the kind of processing performed when the instruction is encountered. The following processors are available:
  • code - Copies all or part of a source code file into a code block in the output
  • exec - Compiles and executes a Java file, copying all or part of the output to a code block
  • plot - Compiles and executes a Java file that creates plots using PlotBuilder, saving the rendered plot to an image file.
The processor type is followed by some number of arguments. These arguments are formatted as key=value pairs. Some useful arguments include:
  • src - The source code file containing the code being displayed or executed.
  • lines - The line number (lines=5), range (lines=5:10), or slice (lines=:-1) of the code being referenced.
  • id - Alternative to line numbers, referencing a block of code between // begin-example: <id> and // end-example: <id> comments.
  • preserveComments, preserveIndentation, preserveTabs, etc. - Formatting flags that determine how source code is displayed. Since these are boolean-valued, the value can be omitted.
These instructions are placed immediately before the block of text they will be updating. For example: 

   <!-- :code: src=examples/Example1.java lines=5:10 preserveComments -->
   
   ```java
   // The code block being synced by the instruction above
   ```
This utility can be run in validate-only mode or update mode. In validate mode, any changes to the files will result in an error. This is useful in CI to validate the docs are up-to-date. In update mode, the files are updated with any changes.

  • Constructor Details

    • UpdateCodeSamples

      public UpdateCodeSamples()
      Creates a new instance of the command line utility to update code examples.

  • Method Details

    • getOptions

      public org.apache.commons.cli.Options getOptions()
      Description copied from class: CommandLineUtility
      Returns the options made available by this command line utility. The base implementation automatically provides the -h,--help option. Implementations overriding this method and begin with a call to super.getOptions().
      Overrides:
      getOptions in class CommandLineUtility
      Returns:
      the options made available by this command line utility

    • run

      public void run(org.apache.commons.cli.CommandLine commandLine) throws Exception
      Description copied from class: CommandLineUtility
      Runs this command line utility with the specified command line arguments.
      Specified by:
      run in class CommandLineUtility
      Parameters:
      commandLine - the command line arguments
      Throws:
      Exception - if any exception occurred while running this command

    • process

      public boolean process(File file) throws IOException
      Processes a single file, validating or updating code samples. The file is skipped if the file type is not recognized.
      Parameters:
      file - the file to process
      Returns:
      true if the file was modified
      Throws:
      IOException - if an I/O error occurred while processing the file

    • getFileFormatter

      protected org.moeaframework.util.cli.UpdateCodeSamples.FileFormatter getFileFormatter(File file)
      Returns the matching file formatter from the given file based on its extension.
      Parameters:
      file - the file
      Returns:
      the matching file formatter, or null if no match found

    • getLanguage

      protected org.moeaframework.util.cli.UpdateCodeSamples.Language getLanguage(File file)
      Returns the matching source language from the given file based on its extension.
      Parameters:
      file - the file
      Returns:
      the matching source language

    • getLanguageForExtension

      protected org.moeaframework.util.cli.UpdateCodeSamples.Language getLanguageForExtension(String extension)
      Returns the matching source language from the given file extension.
      Parameters:
      extension - the file extension
      Returns:
      the matching source language

    • getProcessor

      protected org.moeaframework.util.cli.UpdateCodeSamples.Processor getProcessor(String value)
      Returns the matching processor from its name.
      Parameters:
      value - the name of the processor
      Returns:
      the matching processor
      Throws:
      IllegalArgumentException - if the processor is not supported

    • main

      public static void main(String[] args) throws Exception
      The main entry point for this command line utility.
      Parameters:
      args - the command line arguments
      Throws:
      Exception - if an error occurred