Package org.moeaframework.util.io

Class UpdateCodeSamples

java.lang.Object
org.moeaframework.util.CommandLineUtility
org.moeaframework.util.io.UpdateCodeSamples
public class UpdateCodeSamples extends CommandLineUtility
Utility to update code samples and output found in various documents, including Markdown and HTML / XSLT files. The aim is to inject real Java examples into the documentation so that all code snippets can be tested and validated. This works by embedding a special comment before the code block in one of the supported UpdateCodeSamples.FileType. When processing the document, the code block immediately following the comment is validated or updated from the referenced code. 

   <!-- java:examples/Example1.java -->
 
   ```java
   ... code block updated from referenced Java file ...
   ```

The format of the comment is: 

<!-- <language>:<filename> [<startingLine>:<endingLine>|<id>] {<flag>,...} -->
  • <language> is the name of the programming language. A special case is output, which compiles, executes, and captures the output of the program.
  • [<startingLine>:<endingLine>] specifies the line numbers, starting at index 1, to extract from the file. If no line numbers are provided, the entire content is copied.
  • Alternatively, if an identifier is given instead of line numbers, the content enclosed by the comments // begin-example:<id> and // end-example:<id> is copied.
  • {<flag>,...} specifies additional formatting options, such as {keepComments}.
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, InterruptedException
      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:
      InterruptedException - if the process was interrupted
      IOException - if an I/O error occurred while processing the file

    • main

      public static void main(String[] args) throws Exception
      Invokes the command-line utility to update code samples.
      Parameters:
      args - the command-line arguments
      Throws:
      Exception - if an error occurred running the utility