Project In-Line Help: Difference between revisions

From NovaOrdis Knowledge Base
Jump to navigation Jump to search
Line 38: Line 38:


         if (is == null) {
         if (is == null) {
             throw new UserErrorException(
 
                    "no " + HELP_FILE_NAME + " file found on the classpath; this usually means the utility was not built or installed correctly");
             String msg = "no " + HELP_FILE_NAME + " file found on the classpath; this usually means that the application was not built or installed correctly";
            throw new UserErrorException(msg);
         }
         }


Line 45: Line 46:
         BufferedReader br = null;
         BufferedReader br = null;


         try
         try {
        {
 
             br = new BufferedReader(new InputStreamReader(is));
             br = new BufferedReader(new InputStreamReader(is));
             String line;
             String line;
             while((line = br.readLine()) != null)
             while((line = br.readLine()) != null) {
            {
 
                 help += line + "\n";
                 help += line + "\n";
             }
             }
Line 58: Line 59:
             throw new IllegalStateException(e);
             throw new IllegalStateException(e);
         }
         }
         finally
         finally {
        {
 
             if (br != null)
             if (br != null) {
            {
 
                 try {
                 try {
                     br.close();
                     br.close();
                 }
                 }
                 catch(IOException e) {
                 catch(IOException e) {
                     System.err.println("warn: failed to close the input stream");
                     System.err.println("warn: failed to close the input stream");
                 }
                 }

Revision as of 21:48, 24 July 2017

Internal

Overview

The best mechanism so far to display in-line help is to maintain a help.txt file within the resources of the project, embed it into the root of the JAR artifact and dump it at stdout when needed.

Place the text help file ("help.txt" or "HELP.txt") in ./src/main/resources of the project, so it will be automatically bundled by Maven into the final JAR.

The code that reads the help file is the self-contained class InLineHelp that can be placed in the util package of the project.

There's a novaordis-utilities version, in case the project already depends on novaordis-utilities:

https://github.com/NovaOrdis/novaordis-utilities/blob/master/src/main/java/io/novaordis/utilities/help/InLineHelp.java

Example

package ...;

import java.io.BufferedReader;
import java.io.IOException;
import java.io.InputStream;
import java.io.InputStreamReader;

public class InLineHelp {

    // Constants -------------------------------------------------------------------------------------------------------

    public static final String HELP_FILE_NAME="help.txt";

    // Static ----------------------------------------------------------------------------------------------------------

    public static String get() throws UserErrorException {

        InputStream is = InLineHelp.class.getClassLoader().getResourceAsStream(HELP_FILE_NAME);

        if (is == null) {

            String msg = "no " + HELP_FILE_NAME + " file found on the classpath; this usually means that the application was not built or installed correctly";
            throw new UserErrorException(msg);
        }

        String help = "";
        BufferedReader br = null;

        try {

            br = new BufferedReader(new InputStreamReader(is));
            String line;
            while((line = br.readLine()) != null) {

                help += line + "\n";
            }
        }
        catch (Exception e) {

            throw new IllegalStateException(e);
        }
        finally {

            if (br != null) {

                try {

                    br.close();
                }
                catch(IOException e) {

                    System.err.println("warn: failed to close the input stream");
                }
            }
        }

        return help;
    }

    // Attributes ------------------------------------------------------------------------------------------------------

    // Constructors ----------------------------------------------------------------------------------------------------

    // Public ----------------------------------------------------------------------------------------------------------

    // Package protected -----------------------------------------------------------------------------------------------

    // Protected -------------------------------------------------------------------------------------------------------

    // Private ---------------------------------------------------------------------------------------------------------

    // Inner classes ---------------------------------------------------------------------------------------------------

}

Usage

System.out.println(InLineHelp.get());