lib/kramdown/document.rb in kramdown-0.13.3 vs lib/kramdown/document.rb in kramdown-0.13.4

- old
+ new

@@ -21,10 +21,11 @@ # require 'kramdown/compatibility' require 'kramdown/version' +require 'kramdown/element' require 'kramdown/error' require 'kramdown/parser' require 'kramdown/converter' require 'kramdown/options' require 'kramdown/utils' @@ -106,503 +107,9 @@ end end def inspect #:nodoc: "<KD:Document: options=#{@options.inspect} root=#{@root.inspect} warnings=#{@warnings.inspect}>" - end - - end - - - # Represents all elements in the element tree. - # - # kramdown only uses this one class for representing all available elements in an element tree - # (paragraphs, headers, emphasis, ...). The type of element can be set via the #type accessor. - # - # Following is a description of all supported element types. - # - # == Structural Elements - # - # === :root - # - # [Category] None - # [Usage context] As the root element of a document - # [Content model] Block-level elements - # - # Represents the root of a kramdown document. - # - # The root element contains the following option keys: - # - # :encoding:: When running on Ruby 1.9 this key has to be set to the encoding used for the text - # parts of the kramdown document. - # - # :abbrev_defs:: This key may be used to store the mapping of abbreviation to abbreviation - # definition. - # - # - # === :blank - # - # [Category] Block-level element - # [Usage context] Where block-level elements are expected - # [Content model] Empty - # - # Represents one or more blank lines. It is not allowed to have two or more consecutive blank - # elements. - # - # The +value+ field may contain the original content of the blank lines. - # - # - # === :p - # - # [Category] Block-level element - # [Usage context] Where block-level elements are expected - # [Content model] Span-level elements - # - # Represents a paragraph. - # - # If the option :transparent is +true+, this element just represents a block of text. I.e. this - # element just functions as a container for span-level elements. - # - # - # === :header - # - # [Category] Block-level element - # [Usage context] Where block-level elements are expected - # [Content model] Span-level elements - # - # Represents a header. - # - # The option :level specifies the header level and has to contain a number between 1 and \6. The - # option :raw_text has to contain the raw header text. - # - # - # === :blockquote - # - # [Category] Block-level element - # [Usage context] Where block-level elements are expected - # [Content model] Block-level elements - # - # Represents a blockquote. - # - # - # === :codeblock - # - # [Category] Block-level element - # [Usage context] Where block-level elements are expected - # [Content model] Empty - # - # Represents a code block, i.e. a block of text that should be used as-is. - # - # The +value+ field has to contain the content of the code block. - # - # - # === :ul - # - # [Category] Block-level element - # [Usage context] Where block-level elements are expected - # [Content model] One or more :li elements - # - # Represents an unordered list. - # - # - # === :ol - # - # [Category] Block-level element - # [Usage context] Where block-level elements are expected - # [Content model] One or more :li elements - # - # Represents an ordered list. - # - # - # === :li - # - # [Category] None - # [Usage context] Inside :ol and :ul elements - # [Content model] Block-level elements - # - # Represents a list item of an ordered or unordered list. - # - # - # === :dl - # - # [Category] Block-level element - # [Usage context] Where block-level elements are expected - # [Content model] One or more groups each consisting of one or more :dt elements followed by one - # or more :dd elements. - # - # Represents a definition list which contains groups consisting of terms and definitions for them. - # - # - # === :dt - # - # [Category] None - # [Usage context] Before :dt or :dd elements inside a :dl elment - # [Content model] Span-level elements - # - # Represents the term part of a term-definition group in a definition list. - # - # - # === :dd - # - # [Category] None - # [Usage context] After :dt or :dd elements inside a :dl elment - # [Content model] Block-level elements - # - # Represents the definition part of a term-definition group in a definition list. - # - # - # === :hr - # - # [Category] Block-level element - # [Usage context] Where block-level elements are expected - # [Content model] None - # - # Represents a horizontal line. - # - # - # === :table - # - # [Category] Block-level element - # [Usage context] Where block-level elements are expected - # [Content model] Zero or one :thead elements, one or more :tbody elements, zero or one :tfoot - # elements - # - # Represents a table. Each table row (i.e. :tr element) of the table has to contain the same - # number of :td elements. - # - # The option :alignment has to be an array containing the alignment values, exactly one for each - # column of the table. The possible alignment values are :left, :center, :right and :default. - # - # - # === :thead - # - # [Category] None - # [Usage context] As first element inside a :table element - # [Content model] One or more :tr elements - # - # Represents the table header. - # - # - # === :tbody - # - # [Category] None - # [Usage context] After a :thead element but before a :tfoot element inside a :table element - # [Content model] One or more :tr elements - # - # Represents a table body. - # - # - # === :tfoot - # - # [Category] None - # [Usage context] As last element inside a :table element - # [Content model] One or more :tr elements - # - # Represents the table footer. - # - # - # === :tr - # - # [Category] None - # [Usage context] Inside :thead, :tbody and :tfoot elements - # [Content model] One or more :td elements - # - # Represents a table row. - # - # - # === :td - # - # [Category] None - # [Usage context] Inside :tr elements - # [Content model] As child of :thead/:tr span-level elements, as child of :tbody/:tr and - # :tfoot/:tr block-level elements - # - # Represents a table cell. - # - # - # === :math - # - # [Category] Block/span-level element - # [Usage context] Where block/span-level elements are expected - # [Content model] None - # - # Represents mathematical text that is written in LaTeX. - # - # The +value+ field has to contain the actual mathematical text. - # - # The option :category has to be set to either :span or :block depending on the context where the - # element is used. - # - # - # == Text Markup Elements - # - # === :text - # - # [Category] Span-level element - # [Usage context] Where span-level elements are expected - # [Content model] None - # - # Represents text. - # - # The +value+ field has to contain the text itself. - # - # - # === :br - # - # [Category] Span-level element - # [Usage context] Where span-level elements are expected - # [Content model] None - # - # Represents a hard line break. - # - # - # === :a - # - # [Category] Span-level element - # [Usage context] Where span-level elements are expected - # [Content model] Span-level elements - # - # Represents a link to an URL. - # - # The attribute +href+ has to be set to the URL to which the link points. The attribute +title+ - # optionally contains the title of the link. - # - # - # === :img - # - # [Category] Span-level element - # [Usage context] Where span-level elements are expected - # [Content model] None - # - # Represents an image. - # - # The attribute +src+ has to be set to the URL of the image. The attribute +alt+ has to contain a - # text description of the image. The attribute +title+ optionally contains the title of the image. - # - # - # === :codespan - # - # [Category] Span-level element - # [Usage context] Where span-level elements are expected - # [Content model] None - # - # Represents verbatim text. - # - # The +value+ field has to contain the content of the code span. - # - # - # === :footnote - # - # [Category] Span-level element - # [Usage context] Where span-level elements are expected - # [Content model] None - # - # Represents a footnote marker. - # - # The +value+ field has to contain an element whose children are the content of the footnote. The - # option :name has to contain a valid and unique footnote name. A valid footnote name consists of - # a word character or a digit and then optionally followed by other word characters, digits or - # dashes. - # - # - # === :em - # - # [Category] Span-level element - # [Usage context] Where span-level elements are expected - # [Content model] Span-level elements - # - # Represents emphasis of its contents. - # - # - # === :strong - # - # [Category] Span-level element - # [Usage context] Where span-level elements are expected - # [Content model] Span-level elements - # - # Represents strong importance for its contents. - # - # - # === :entity - # - # [Category] Span-level element - # [Usage context] Where span-level elements are expected - # [Content model] None - # - # Represents an HTML entity. - # - # The +value+ field has to contain an instance of Kramdown::Utils::Entities::Entity. The option - # :original can be used to store the original representation of the entity. - # - # - # === :typographic_sym - # - # [Category] Span-level element - # [Usage context] Where span-level elements are expected - # [Content model] None - # - # Represents a typographic symbol. - # - # The +value+ field needs to contain a Symbol representing the specific typographic symbol from - # the following list: - # - # :mdash:: An mdash character (---) - # :ndash:: An ndash character (--) - # :hellip:: An ellipsis (...) - # :laquo:: A left guillemet (<<) - # :raquo:: A right guillemet (>>) - # :laquo_space:: A left guillemet with a space (<< ) - # :raquo_space:: A right guillemet with a space ( >>) - # - # - # === :smart_quote - # - # [Category] Span-level element - # [Usage context] Where span-level elements are expected - # [Content model] None - # - # Represents a quotation character. - # - # The +value+ field needs to contain a Symbol representing the specific quotation character: - # - # :lsquo:: Left single quote - # :rsquo:: Right single quote - # :ldquo:: Left double quote - # :rdquo:: Right double quote - # - # - # === :abbreviation - # - # [Category] Span-level element - # [Usage context] Where span-level elements are expected - # [Content model] None - # - # Represents a text part that is an abbreviation. - # - # The +value+ field has to contain the text part that is the abbreviation. The definition of the - # abbreviation is stored in the :root element of the document. - # - # - # == Other Elements - # - # === :html_element - # - # [Category] Block/span-level element - # [Usage context] Where block/span-level elements or raw HTML elements are expected - # [Content model] Depends on the element - # - # Represents an HTML element. - # - # The +value+ field has to contain the name of the HTML element the element is representing. - # - # The option :category has to be set to either :span or :block depending on the whether the - # element is a block-level or a span-level element. The option :content_model has to be set to the - # content model for the element (either :block if it contains block-level elements, :span if it - # contains span-level elements or :raw if it contains raw content). - # - # - # === :xml_comment - # - # [Category] Block/span-level element - # [Usage context] Where block/span-level elements are expected or in raw HTML elements - # [Content model] None - # - # Represents an XML/HTML comment. - # - # The +value+ field has to contain the whole XML/HTML comment including the delimiters. - # - # The option :category has to be set to either :span or :block depending on the context where the - # element is used. - # - # - # === :xml_pi - # - # [Category] Block/span-level element - # [Usage context] Where block/span-level elements are expected or in raw HTML elements - # [Content model] None - # - # Represents an XML/HTML processing instruction. - # - # The +value+ field has to contain the whole XML/HTML processing instruction including the - # delimiters. - # - # The option :category has to be set to either :span or :block depending on the context where the - # element is used. - # - # - # === :comment - # - # [Category] Block/span-level element - # [Usage context] Where block/span-level elements are expected - # [Content model] None - # - # Represents a comment. - # - # The +value+ field has to contain the comment. - # - # The option :category has to be set to either :span or :block depending on the context where the - # element is used. - # - # - # === :raw - # - # [Category] Block/span-level element - # [Usage context] Where block/span-level elements are expected - # [Content model] None - # - # Represents a raw string that should not be modified. For example, the element could contain some - # HTML code that should be output as-is without modification and escaping. - # - # The +value+ field has to contain the actual raw text. - # - # The option :category has to be set to either :span or :block depending on the context where the - # element is used. The option :type can be set to an array of strings to define for which - # converters the raw string is valid. - class Element - - # A symbol representing the element type. For example, :p or :blockquote. - attr_accessor :type - - # The value of the element. The interpretation of this field depends on the type of the element. - # Many elements don't use this field. - attr_accessor :value - - # The child elements of this element. - attr_accessor :children - - - # Create a new Element object of type +type+. The optional parameters +value+, +attr+ and - # +options+ can also be set in this constructor for convenience. - def initialize(type, value = nil, attr = nil, options = nil) - @type, @value, @attr, @options = type, value, (Utils::OrderedHash.new.merge!(attr) if attr), options - @children = [] - end - - # The attributes of the element. Uses an Utils::OrderedHash to retain the insertion order. - def attr - @attr ||= Utils::OrderedHash.new - end - - # The options hash for the element. It is used for storing arbitray options. - def options - @options ||= {} - end - - def inspect #:nodoc: - "<kd:#{@type}#{@value.nil? ? '' : ' ' + @value.inspect} #{@attr.inspect}#{options.empty? ? '' : ' ' + @options.inspect}#{@children.empty? ? '' : ' ' + @children.inspect}>" - end - - CATEGORY = {} # :nodoc: - [:blank, :p, :header, :blockquote, :codeblock, :ul, :ol, :dl, :table, :hr].each {|b| CATEGORY[b] = :block} - [:text, :a, :br, :img, :codespan, :footnote, :em, :strong, :entity, :typographic_sym, - :smart_quote, :abbreviation].each {|b| CATEGORY[b] = :span} - - # Return the category of +el+ which can be :block, :span or +nil+. - # - # Most elements have a fixed category, however, some elements can either appear in a block-level - # or a span-level context. These elements need to have the option :category correctly set. - def self.category(el) - CATEGORY[el.type] || el.options[:category] end end end