Bukkit-API  1.7.9-R0.2
The inofficial Bukkit-API
HelpTopic.java
1 package org.bukkit.help;
2 
4 import org.bukkit.entity.Player;
5 
6 /**
7  * HelpTopic implementations are displayed to the user when the user uses the
8  * /help command.
9  * <p>
10  * Custom implementations of this class can work at two levels. A simple
11  * implementation only needs to set the value of {@code name}, {@code
12  * shortText}, and {@code fullText} in the constructor. This base class will
13  * take care of the rest.
14  * <p>
15  * Complex implementations can be created by overriding the behavior of all
16  * the methods in this class.
17  */
18 public abstract class HelpTopic {
19  protected String name;
20  protected String shortText;
21  protected String fullText;
22  protected String amendedPermission;
23 
24  /**
25  * Determines if a {@link Player} is allowed to see this help topic.
26  * <p>
27  * HelpTopic implementations should take server administrator wishes into
28  * account as set by the {@link HelpTopic#amendCanSee(String)} function.
29  *
30  * @param player The Player in question.
31  * @return True of the Player can see this help topic, false otherwise.
32  */
33  public abstract boolean canSee(CommandSender player);
34 
35  /**
36  * Allows the server administrator to override the permission required to
37  * see a help topic.
38  * <p>
39  * HelpTopic implementations should take this into account when
40  * determining topic visibility on the {@link
41  * HelpTopic#canSee(org.bukkit.command.CommandSender)} function.
42  *
43  * @param amendedPermission The permission node the server administrator
44  * wishes to apply to this topic.
45  */
46  public void amendCanSee(String amendedPermission) {
47  this.amendedPermission = amendedPermission;
48  }
49 
50  /**
51  * Returns the name of this help topic.
52  *
53  * @return The topic name.
54  */
55  public String getName() {
56  return name;
57  }
58 
59  /**
60  * Returns a brief description that will be displayed in the topic index.
61  *
62  * @return A brief topic description.
63  */
64  public String getShortText() {
65  return shortText;
66  }
67 
68  /**
69  * Returns the full description of this help topic that is displayed when
70  * the user requests this topic's details.
71  * <p>
72  * The result will be paginated to properly fit the user's client.
73  *
74  * @param forWho The player or console requesting the full text. Useful
75  * for further security trimming the command's full text based on
76  * sub-permissions in custom implementations.
77  *
78  * @return A full topic description.
79  */
80  public String getFullText(CommandSender forWho) {
81  return fullText;
82  }
83 
84  /**
85  * Allows the server admin (or another plugin) to add or replace the
86  * contents of a help topic.
87  * <p>
88  * A null in either parameter will leave that part of the topic unchanged.
89  * In either amending parameter, the string {@literal <text>} is replaced
90  * with the existing contents in the help topic. Use this to append or
91  * prepend additional content into an automatically generated help topic.
92  *
93  * @param amendedShortText The new topic short text to use, or null to
94  * leave alone.
95  * @param amendedFullText The new topic full text to use, or null to leave
96  * alone.
97  */
98  public void amendTopic(String amendedShortText, String amendedFullText) {
99  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 }
void amendCanSee(String amendedPermission)
Definition: HelpTopic.java:46
String applyAmendment(String baseText, String amendment)
Definition: HelpTopic.java:114
String getFullText(CommandSender forWho)
Definition: HelpTopic.java:80
void amendTopic(String amendedShortText, String amendedFullText)
Definition: HelpTopic.java:98
abstract boolean canSee(CommandSender player)