/brz/remove-bazaar

To get this branch, use:
bzr branch http://gegoxaren.bato24.eu/bzr/brz/remove-bazaar

« back to all changes in this revision

Viewing changes to bzrlib/help_topics.py

  • Committer: John Arbash Meinel
  • Date: 2006-11-08 16:24:19 UTC
  • mto: This revision was merged to the branch mainline in revision 2126.
  • Revision ID: john@arbash-meinel.com-20061108162419-5b725384876fc939
Switch help_topics to use a Registry.
This also involves changing the API for topics so that the detail
function returns a string, rather than assuming that all uses of
help topics will be for writing to a file.

Show diffs side-by-side

added added

removed removed

Lines of Context:
bzrlib/help_topics.py
20
20
help bzr become fully learnable without referring to a tutorial.
21
21
"""
22
22
 
23
 
import sys
24
 
 
25
 
 
26
 
_HELP_TOPICS={}
27
 
 
28
 
 
29
 
def add_topic(topic, detail, summary):
30
 
    """Add documentation for a new topic.
31
 
 
32
 
    :param topic:  Name of documentation entry.
33
 
    :param detail:  Function or string object providing detailed
34
 
    documentation for topic.  Function interface is detail(topic, outfile).
35
 
    :param summary:  String providing single-line documentation for topic.
36
 
 
37
 
    """
38
 
    _HELP_TOPICS[topic]=(detail, summary)
39
 
 
40
 
def write_topic(topic, outfile=sys.stdout):
41
 
    """write to outfile the topic named "name"""
42
 
    obj, comment = _HELP_TOPICS[topic]
43
 
    if callable(obj):
44
 
        obj(topic, outfile)
45
 
    else:
46
 
        outfile.write(obj)
47
 
 
48
 
 
49
 
def is_topic(name):
50
 
    """is "name" a topic ?"""
51
 
    return name in _HELP_TOPICS.keys( )
52
 
 
53
 
 
54
 
def get_topics_list( ):
55
 
    """return a dict like {topic_name:topi_comment}"""
56
 
    return _HELP_TOPICS.keys( )
57
 
 
58
 
def get_topic_summary(topic):
59
 
    """return the topic summary"""
60
 
    obj, summary = _HELP_TOPICS[topic]
61
 
    return summary
62
 
    
63
 
 
64
 
 
 
23
from bzrlib import registry
 
24
 
 
25
 
 
26
class HelpTopicRegistry(registry.Registry):
 
27
    """A Regsitry customized for handling help topics."""
 
28
 
 
29
    def register(self, topic, detail, summary):
 
30
        """Register a new help topic.
 
31
 
 
32
        :param topic: Name of documentation entry
 
33
        :param detail: Function or string object providing detailed
 
34
            documentation for topic.  Function interface is detail(topic).
 
35
            This should return a text string of the detailed information.
 
36
        :param summary: String providing single-line documentation for topic.
 
37
        """
 
38
        # The detail is stored as the 'object' and the 
 
39
        super(HelpTopicRegistry, self).register(topic, detail, info=summary)
 
40
 
 
41
    def register_lazy(self, topic, module_name, member_name, summary):
 
42
        """Register a new help topic, and import the details on demand.
 
43
 
 
44
        :param topic: Name of documentation entry
 
45
        :param module_name: The module to find the detailed help.
 
46
        :param member_name: The member of the module to use for detailed help.
 
47
        :param summary: String providing single-line documentation for topic.
 
48
        """
 
49
        super(HelpTopicRegistry, self).register(topic, module_name,
 
50
                                                member_name, info=summary)
 
51
 
 
52
    def get_detail(self, topic):
 
53
        """Get the detailed help on a given topic."""
 
54
        obj = self.get(topic)
 
55
        if callable(obj):
 
56
            return obj(topic)
 
57
        else:
 
58
            return obj
 
59
 
 
60
    def get_summary(self, topic):
 
61
        """Get the single line summary for the topic."""
 
62
        return self.get_info(topic)
 
63
 
 
64
 
 
65
topic_registry = HelpTopicRegistry()
65
66
 
66
67
 
67
68
#----------------------------------------------------
68
69
 
69
 
def _help_on_topics(dummy, outfile):
 
70
def _help_on_topics(dummy):
70
71
    """Write out the help for topics to outfile"""
71
72
 
72
 
    topics = get_topics_list()
 
73
    topics = topic_registry.keys()
73
74
    lmax = max(len(topic) for topic in topics)
74
75
        
 
76
    out = []
75
77
    for topic in topics:
76
 
        summary = get_topic_summary(topic)
77
 
        spaces = " " * (lmax-len(topic))
78
 
        outfile.write("%s%s %s\n" % (topic, spaces, summary))
79
 
 
80
 
 
81
 
def _help_on_revisionspec(name, outfile):
 
78
        summary = topic_registry.get_summary(topic)
 
79
        out.append("%-*s %s\n" % (lmax, topic, summary))
 
80
    return ''.join(out)
 
81
 
 
82
 
 
83
def _help_on_revisionspec(name):
82
84
    """"Write the summary help for all documented topics to outfile."""
83
85
    import bzrlib.revisionspec
84
86
 
85
 
    outfile.write("\nRevision prefix specifier:"
86
 
                  "\n--------------------------\n")
 
87
    out = []
 
88
    out.append("\nRevision prefix specifier:"
 
89
               "\n--------------------------\n")
87
90
 
88
91
    for i in bzrlib.revisionspec.SPEC_TYPES:
89
92
        doc = i.__doc__
92
95
        while (doc[-2:] == '\n\n' or doc[-1:] == ' '):
93
96
            doc = doc[:-1]
94
97
 
95
 
        outfile.write("  %s %s\n\n" % (i.prefix, doc))
 
98
        out.append("  %s %s\n\n" % (i.prefix, doc))
 
99
 
 
100
    return ''.join(out)
96
101
 
97
102
 
98
103
_basic_help= \
123
128
"""
124
129
 
125
130
 
126
 
add_topic("revisionspec", _help_on_revisionspec, "Revisions specifier")
127
 
add_topic("basic", _basic_help, "Basic commands")
128
 
add_topic("topics", _help_on_topics, "Topics list")
 
131
topic_registry.register("revisionspec", _help_on_revisionspec,
 
132
                        "Explain how to use --revision")
 
133
topic_registry.register('basic', _basic_help, "Basic commands")
 
134
topic_registry.register('topics', _help_on_topics, "Topics list")