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