Project In-Line Help: Difference between revisions

From NovaOrdis Knowledge Base
Jump to navigation Jump to search
No edit summary
 
(12 intermediate revisions by the same user not shown)
Line 5: Line 5:
=Overview=
=Overview=


The best mechanism so far 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.
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") in <tt>./src/main/resources</tt> of the project, it'll be bundled by Maven into the final JAR.
Place the text help file ("help.txt" or "HELP.txt") in <tt>./src/main/resources</tt> 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 <tt>util</tt> package of the project:
The code that reads the help file is the self-contained class InLineHelp that can be placed in the <tt>util</tt> package of the project.


<pre>
=Implementation=
package ...;


import java.io.BufferedReader;
There's a novaordis-utilities version, in case the project already depends on novaordis-utilities:
import java.io.IOException;
import java.io.InputStream;
import java.io.InputStreamReader;


public class InLineHelp {
{{External|https://github.com/NovaOrdis/novaordis-utilities/blob/master/src/main/java/io/novaordis/utilities/help/InLineHelp.java}}


    // Constants -------------------------------------------------------------------------------------------------------
InLineHelp.java can be used as a starting point for a standalone implementation.


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


    // Static ----------------------------------------------------------------------------------------------------------
<syntaxhighlight lang='java'>
try {


     public static String get() throws UserErrorException {
     System.out.println(InLineHelp.get());
 
}
        InputStream is = InLineHelp.class.getClassLoader().getResourceAsStream(HELP_FILE_NAME);
catch(UserErrorException e) {
 
        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 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 ---------------------------------------------------------------------------------------------------


    System.err.println(e.getMessage());
}
}
</syntaxhighlight>


</pre>
=Line Length=


=Usage=
103 characters.


<pre>
0123456789##########0123456789##########0123456789## 103 ###0123456789##########0123456789##########123
System.out.println(InLineHelp.get());
</pre>

Latest revision as of 07:46, 23 March 2019

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.

Implementation

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

InLineHelp.java can be used as a starting point for a standalone implementation.

Usage

try {

    System.out.println(InLineHelp.get());
}
catch(UserErrorException e) {

    System.err.println(e.getMessage());
}

Line Length

103 characters. 

0123456789##########0123456789##########0123456789## 103 ###0123456789##########0123456789##########123
Retrieved from "https://kb.novaordis.com/index.php?title=Project_In-Line_Help&oldid=56767"