]> git.wincent.com - wikitext.git/blob - doc/rdoc.rb
b7405753c5a090eaa31dcf8ce6c38af526ed8ea3
[wikitext.git] / doc / rdoc.rb
1 # The Wikitext module provides a namespace for all of the extension.
2 # In practice, all your interaction will be with the Wikitext::Parser
3 # class.
4 module Wikitext
5
6   # = Attributes
7   #
8   # == +line_ending+ (String)
9   #
10   # The line ending to be used in the generated HTML (defaults to "\n").
11   #
12   # == +internal_link_prefix+ (String)
13   #
14   # The prefix to be prepended to internal links (defaults to "/wiki/").
15   # For example, given an +internal_link_prefix+ of "/wiki/", the internal
16   # link:
17   #
18   #     !!!wikitext
19   #     [[Apple]]
20   #
21   # would be transformed into:
22   #
23   #     !!!html
24   #     <a href="/wiki/Apple">Apple</a>
25   #
26   # == +external_link_class+ (String)
27   #
28   # The CSS class to be applied to external links (defaults to "external").
29   # For example, given an +external_link_class+ of "external", the external
30   # link:
31   #
32   #     !!!wikitext
33   #     [http://www.google.com/ the best search engine]
34   #
35   # would be transformed into:
36   #
37   #     !!!html
38   #     <a class="external" href="http://www.google.com/">the best search engine</a>
39   #
40   # == +external_link_rel+ (String)
41   #
42   # The +rel+ attribute to be applied to external links (defaults to +nil+,
43   # meaning that no +rel+ attribute is applied). Setting a +rel+ attribute of
44   # "nofollow" may be useful for search-engine optimization (see
45   # http://en.wikipedia.org/wiki/Nofollow for more details).
46   #
47   # This attribute can be set during initialization:
48   #
49   #     parser = Wikitext::Parser.new :external_link_rel => 'nofollow'
50   #
51   # Or via setting an attribute on the parser:
52   #
53   #     parser = Wikitext::Parser.new
54   #     parser.external_link_rel = 'nofollow'
55   #
56   # Or at parse time:
57   #
58   #     parser = Wikitext::Parser.new
59   #     parser.parse input, :external_link_rel => 'nofollow'
60   #
61   # Setting +external_link_rel+ to +nil+ suppresses the emission of any
62   # previously configured +rel+ attribute:
63   #
64   #     parser.parse input, :external_link_rel => nil
65   #
66   # == +mailto_class+ (String)
67   #
68   # The CSS class to be applied to external "mailto" links (defaults to
69   # "mailto"). For example:
70   #
71   #     !!!wikitext
72   #     [mailto:user@example.com user@example.com]
73   #
74   # or if autolinking of email addresses is turned on, just:
75   #
76   #     !!!wikitext
77   #     user@example.com
78   #
79   # would be transformed into:
80   #
81   #     !!!html
82   #     <a class="mailto" href="mailto:user@example.com">user@example.com</a>
83   #
84   # == +img_prefix+ (String)
85   #
86   # The prefix to be prepended to image tags (defaults to "/images/").
87   # For example, given this image markup:
88   #
89   #     !!!wikitext
90   #     {{foo.png}}
91   #
92   # The following +img+ tag would be produced:
93   #
94   #     !!!html
95   #     <img src="/images/foo.png" alt="foo.png" />
96   #
97   # == +autolink+ (boolean)
98   #
99   # Whether to autolink URIs found in the plain scope.
100   # When true:
101   #
102   #     !!!wikitext
103   #     http://apple.com/
104   #
105   # will be transformed to:
106   #
107   #     !!!html
108   #     <a href="http://apple.com/">http://apple.com/</a>
109   #
110   # and if an external_link_class is set (to "external", for example) then
111   # the transformation will be:
112   #
113   #     !!!html
114   #     <a class="external" href="http://apple.com/">http://apple.com/</a>
115   #
116   # When false, no transformation will be applied and the link will be
117   # echoed literally:
118   #
119   #     !!!html
120   #     http://apple.com/
121   #
122   # == +space_to_underscore+ (boolean)
123   #
124   # Whether spaces in link targets should be encoded normally or transformed
125   # into underscores.
126   #
127   # When false, an internal link like:
128   #
129   #     !!!wikitext
130   #     [[foo bar]]
131   #
132   # Would be converted into:
133   #
134   #     !!!html
135   #     <a href="/wiki/foo%20bar">foo bar</a>
136   #
137   # But when true (the default), it would be converted into:
138   #
139   #     !!!html
140   #     <a href="/wiki/foo_bar">foo bar</a>
141   #
142   # Converting spaces to underscores makes most URLs prettier, but it comes at
143   # a cost: when this mode is true the articles "foo bar" and "foo_bar" can no
144   # longer be disambiguated, and a link to "foo_bar" will actually resolve to
145   # "foo bar"; it is therefore recommended that you explicitly disallow
146   # underscores in titles at the application level so as to avoid this kind of
147   # confusion.
148   #
149   # == +base_heading_level+ (integer)
150   #
151   # An integer between 0 and 6 denoting the current "heading level".
152   # This can be used to inform the parser of the "context" in which
153   # it is translating markup.
154   #
155   # For example, the parser might be translating blog post excerpts
156   # on a page where there is an "h1" title element for the page itself
157   # and an "h2" title element for each excerpt. In this context it is
158   # useful to set +base_heading_level+ to 2, so that any "top level"
159   # headings in the markup (that is "h1" elements) can be automatically
160   # transformed into "h3" elements so that they appear to be
161   # appropriately "nested" inside the containing page elements.
162   #
163   # In this way, markup authors can be freed from thinking about
164   # which header size they should use and just always start from "h1"
165   # for their most general content and work their way down.
166   #
167   # An additional benefit is that markup can be used in different
168   # contexts at different levels of nesting and the headings will be
169   # adjusted to suit automatically with no intervention from the
170   # markup author.
171   #
172   # Finally, it's worth noting that in contexts where the user input
173   # is not necessarily trusted, this setting can be used to prevent
174   # users from inappropriately employing "h1" tags in deeply-nested
175   # contexts where they would otherwise disturb the visual harmony of
176   # the page.
177   #
178   # == +output_style+ (Symbol)
179   #
180   # Wikitext emits valid HTML5 fragments. By default, the output syntax is
181   # HTML. Optionally, the output syntax can be changed to XML by setting the
182   # +output_style+ to ":xml".
183   #
184   # This can be done during initialization:
185   #
186   #     parser = Wikitext::Parser.new :output_style => :xml
187   #
188   # Or via setting an attribute on the parser:
189   #
190   #     parser = Wikitext::Parser.new
191   #     parser.output_style = :xml
192   #
193   # Or at parse time:
194   #
195   #     parser = Wikitext::Parser.new
196   #     parser.parse input, :output_style => :xml
197   #
198   # In practice the only difference between the two output syntaxes is that
199   # the XML syntax uses self closing +img+ tags:
200   #
201   #     !!!html
202   #     <img src="foo.png" alt="Foo" />
203   #
204   # While the HTML syntax does not:
205   #
206   #     !!!html
207   #     <img src="foo.png" alt="Foo">
208   #
209   # == +link_proc+ (lambda or Proc object)
210   #
211   # "Red links" can be implemented by providing a custom +link_proc+ block
212   # at parse time. This can be used to check for existing or non-existent
213   # link targets and apply custom CSS styling accordingly. For example,
214   # consider:
215   #
216   #     link_proc = lambda { |target| target == 'bar' ? 'redlink' : nil }
217   #     Wikitext::Parser.new.parse '[[foo]] [[bar]]', :link_proc => link_proc
218   #
219   # This would add the "redlink" CSS class to the "bar" link but not the
220   # "foo" link. Please note that if your +link_proc+ involves database
221   # queries then you should implement an appropriate caching strategy to
222   # ensure that markup with many links does not overwhelm your database.
223   #
224   # A +link_proc+ may also be set during initialization:
225   #
226   #     parser = Wikitext::Parser.new :link_proc => link_proc
227   #
228   # Or via setting an attribute on the parser:
229   #
230   #     parser = Wikitext::Parser.new
231   #     parser.link_proc = link_proc
232   #
233   # Many more examples of link procs can be found in the spec suite:
234   #
235   # * http://git.wincent.com/wikitext.git/blob/HEAD:/spec/internal_link_spec.rb
236   class Parser
237
238     # Sanitizes an internal link target for inclusion within the HTML
239     # stream. Expects +string+ to be UTF-8-encoded.
240     #
241     # For example, a link target for the article titled:
242     #
243     #     !!!wikitext
244     #     foo, "bar" & baz €
245     #
246     # would be sanitized as:
247     #
248     #     !!!html
249     #     foo, &quot;bar&quot; &amp; baz &#x20ac;
250     #
251     # Note that characters which have special meaning within HTML such as
252     # quotes and ampersands are turned into named entities, and characters
253     # outside of the printable ASCII range are turned into hexadecimal
254     # entities.
255     #
256     # See also encode_link_target.
257     def self.sanitize_link_target string
258       # This is just a placeholder.
259       # See parser.c for the C source code to this method.
260     end
261
262     # URL-encodes an internal link target for use as an href attribute in an
263     # anchor. Expects +string+ to be UTF-8-encoded.
264     #
265     # For example, the link target:
266     #
267     #     !!!wikitext
268     #     foo, "bar" & baz €
269     #
270     # would be encoded as:
271     #
272     #     !!!html
273     #     foo%2c%20%22bar%22%20%26%20baz%e2%82%ac
274     #
275     # The encoding is based on RFCs 2396 and 2718. The "unreserved" characters
276     # a..z, a..Z, 0..9, "-", "_", "." and "~" are passed through unchanged and
277     # all others are converted into percent escapes.
278     #
279     # When combined with sanitize_link_target this method can be used to emit
280     # the following link for the example article:
281     #
282     #     !!!html
283     #     <a href="foo%2c%20%22bar%22%20%26%20baz%e2%82%ac">foo, &quot;bar&quot; &amp; baz &#x20ac;</a>
284     #
285     # Note that when +space_to_underscore+ is +true+ spaces are treated specially,
286     # and are converted to "_" rather than "%20". For the majority of links this
287     # yields much prettier URLs at the cost of some reduction in the namespace of
288     # possible titles (this is because when using +space_to_underscore+ you should
289     # disallow underscores in article titles to avoid ambiguity between titles like
290     # "foo bar" and "foo_bar").
291     def self.encode_link_target string
292       # This is just a placeholder.
293       # See parser.c for the C source code to this method.
294     end
295
296     # Prepares a Parser instance.
297     #
298     # There are a number of attributes that you can set on the returned
299     # parser to customize its behaviour. See the attributes documentation
300     # in the Parser class. You also have the option of overriding the
301     # attributes at initialization time passing in the attribute name in
302     # symbol form together with the overridden value.
303     #
304     # In other words, both:
305     #
306     #     parser = Wikitext::Parser.new
307     #     parser.autolink = false
308     #     parser.mailto_class = 'mail'
309     #
310     # And:
311     #
312     #     parser = Wikitext::Parser.new :autolink => false, :mailto_class => 'mail'
313     #
314     # Are equivalent.
315     def initialize options = {}
316       # This is just a placeholder.
317       # See parser.c for the C source code to this method.
318     end
319
320     # Feeds the UTF-8-encoded +string+ into the scanner and returns an
321     # array of recognized tokens. Raises a Wikitext::Parser::Error
322     # exception if the input string is not valid UTF-8.
323     #
324     # Normally you don't need to invoke this method manually because the
325     # parse method automatically sets up a scanner and obtains tokens as
326     # it needs them. This method exists for testing and introspection
327     # only.
328     def tokenize string
329       # This is just a placeholder.
330       # See parser.c for the C source code to this method.
331     end
332
333     # Like the tokenize method feeds +string+ into the scanner to obtain
334     # the corresponding tokens, but unlike the tokenize method it does not
335     # return them because its sole purpose is to measure the speed of
336     # the scanner.
337     #
338     # Just like the tokenize method raises a Wikitext::Parser::Error if
339     # passed invalid UTF-8 input.
340     def benchmarking_tokenize string
341       # This is just a placeholder.
342       # See parser.c for the C source code to this method.
343     end
344
345     # Parses and transforms the UTF-8 wikitext markup input string into
346     # HTML. Raises a Wikitext::Parser::Error if passed invalid UTF-8.
347     # You can customize some aspects of the transformation by setting
348     # attributes on the parser instance before calling this method
349     # (see the attributes documentation for the Parser class),
350     # or by passing in an (optional) options hash.
351     #
352     # Options that can be overridden at parse-time include:
353     #
354     # +indent+::              A non-negative number (to add an arbitrary
355     #                         amount of indentation to all lines in the
356     #                         output) or false (to disable indentation
357     #                         entirely).
358     # +base_heading_level+::  An integer between 0 and 6 denoting the
359     #                         current "heading level" (documented above).
360     # +output_style+::        A symbol, ":xml", to emit XML syntax (by
361     #                         default HTML syntax is emitted)
362     # +link_proc+::           A lambda that can be used to apply custom
363     #                         CSS to links to produce "red links"
364     #                         (documented above)
365     def parse string, options = {}
366       # This is just a placeholder.
367       # See parser.c for the C source code to this method.
368     end
369
370     # Like the parse method transforms the UTF-8 input +string+ from
371     # wikitext markup into HTML, but doesn't return a result. This
372     # method is specifically designed for performance profiling so
373     # you shouldn't need to call it in practice. It parses the supplied
374     # string 100,000 times so as to provide enough sample data to make
375     # profiling useful while minimizing the influence of extraneous
376     # factors such as set-up code.
377     def profiling_parse string
378       # This is just a placeholder.
379       # See parser.c for the C source code to this method.
380     end
381
382     # Exception raised when an error occurs during parsing.
383     # As the parser is designed to gracefully cope with bad syntax, the
384     # only reason you should see this exception is if you pass
385     # invalidly-encoded UTF-8 to the parse method.
386     class Error < Exception
387     end
388
389     # Token object representing a symbol found in the input stream during
390     # scanning. When you invoke the tokenize method you receive an array
391     # of Token instances.
392     #
393     # This class exists purely for testing and diagnostic purposes; it
394     # is actually just a wrapper for the real token structure that is
395     # used internally.  (In actual use the Wikitext extension doesn't
396     # even use this class; it instead uses lightweight C structs under
397     # the hood for maximum speed and memory efficiency.)
398     #
399     # = Attributes
400     #
401     # +start+::         the location in memory (a character pointer
402     #                   into the input stream) where the token begins
403     # +stop+::          the location in memory (a character pointer)
404     #                   where the token ends
405     # +line_start+::    the line number where the token starts;
406     #                   numbering begins at line 1 (there is no line 0)
407     # +line_stop+::     the line number where the token ends
408     # +column_start+::  the column number where the token start;
409     #                   numbering beings at column 1 (there is no column 0)
410     # +column_stop+::   the column number where the token ends
411     # +code_point+::    for tokens outside the range of printable ASCII
412     #                   the UTF-32 code point corresponding to the token
413     # +token_type+::    the type of the token, from the possible set of
414     #                   token types returned by the types method
415     # +string_value+::  the textal content of the token as a Ruby String
416     class Token
417       # Returns a hashof all token types by (numeric) value and
418       # (human-readable) name.
419       def self.types
420         # This is just a placeholder.
421         # See token.c for the C source code to this method.
422       end
423     end
424   end
425 end