001    package org.bukkit.help;
002    
003    import org.bukkit.command.CommandSender;
004    import org.bukkit.entity.Player;
005    
006    /**
007     * HelpTopic implementations are displayed to the user when the user uses the
008     * /help command.
009     * <p>
010     * Custom implementations of this class can work at two levels. A simple
011     * implementation only needs to set the value of {@code name}, {@code
012     * shortText}, and {@code fullText} in the constructor. This base class will
013     * take care of the rest.
014     * <p>
015     * Complex implementations can be created by overriding the behavior of all
016     * the methods in this class.
017     */
018    public abstract class HelpTopic {
019        protected String name;
020        protected String shortText;
021        protected String fullText;
022        protected String amendedPermission;
023        
024        /**
025         * Determines if a {@link Player} is allowed to see this help topic.
026         * <p>
027         * HelpTopic implementations should take server administrator wishes into
028         * account as set by the {@link HelpTopic#amendCanSee(String)} function.
029         *
030         * @param player The Player in question.
031         * @return True of the Player can see this help topic, false otherwise.
032         */
033        public abstract boolean canSee(CommandSender player);
034    
035        /**
036         * Allows the server administrator to override the permission required to
037         * see a help topic.
038         * <p>
039         * HelpTopic implementations should take this into account when
040         * determining topic visibility on the {@link
041         * HelpTopic#canSee(org.bukkit.command.CommandSender)} function.
042         *
043         * @param amendedPermission The permission node the server administrator
044         *     wishes to apply to this topic.
045         */
046        public void amendCanSee(String amendedPermission) {
047            this.amendedPermission = amendedPermission;
048        }
049    
050        /**
051         * Returns the name of this help topic.
052         *
053         * @return The topic name.
054         */
055        public String getName() {
056            return name;
057        }
058    
059        /**
060         * Returns a brief description that will be displayed in the topic index.
061         *
062         * @return A brief topic description.
063         */
064        public String getShortText() {
065            return shortText;
066        }
067    
068        /**
069         * Returns the full description of this help topic that is displayed when
070         * the user requests this topic's details.
071         * <p>
072         * The result will be paginated to properly fit the user's client.
073         *
074         * @param forWho The player or console requesting the full text. Useful
075         *     for further security trimming the command's full text based on
076         *     sub-permissions in custom implementations.
077         *
078         * @return A full topic description.
079         */
080        public String getFullText(CommandSender forWho) {
081            return fullText;
082        }
083    
084        /**
085         * Allows the server admin (or another plugin) to add or replace the
086         * contents of a help topic.
087         * <p>
088         * A null in either parameter will leave that part of the topic unchanged.
089         * In either amending parameter, the string {@literal <text>} is replaced
090         * with the existing contents in the help topic. Use this to append or
091         * prepend additional content into an automatically generated help topic.
092         *
093         * @param amendedShortText The new topic short text to use, or null to
094         *     leave alone.
095         * @param amendedFullText The new topic full text to use, or null to leave
096         *     alone.
097         */
098        public void amendTopic(String amendedShortText, String amendedFullText) {
099            shortText = applyAmendment(shortText, amendedShortText);
100            fullText = applyAmendment(fullText, amendedFullText);
101        }
102    
103        /**
104         * Developers implementing their own custom HelpTopic implementations can
105         * use this utility method to ensure their implementations comply with the
106         * expected behavior of the {@link HelpTopic#amendTopic(String, String)}
107         * method.
108         *
109         * @param baseText The existing text of the help topic.
110         * @param amendment The amending text from the amendTopic() method.
111         * @return The application of the amending text to the existing text,
112         *     according to the expected rules of amendTopic().
113         */
114        protected String applyAmendment(String baseText, String amendment) {
115            if (amendment == null) {
116                return baseText;
117            } else {
118                return amendment.replaceAll("<text>", baseText);
119            }
120        }
121    }