coradoc-markdown 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e985a5efd633ee5e945c01d6f9465316f36ed682e8a65fa1c6c33304f8af453c
+  data.tar.gz: ece9f3be5276f6ef0c1c325fa59a3f43452472b8aa5e2350ad690381b5b7a173
+SHA512:
+  metadata.gz: 531bc6952f8a55ccbd3b86190ced905b60242bebe6dd65873fee5cc0715fcdaa802147473fb897fb818bdec611937e48eb3b995db4844cd4c7c08a4f575bdbf7
+  data.tar.gz: 022055b32982e6a661bcbcca4e6044e8ccb4f36d265d7f4bbe1575c07e9a424acb711d8dc532a8ba49bc4afd2d56423f0c9be127bb9a996d1cdd5c9e1e738d26

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2023 Abu Nashir
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/lib/coradoc/markdown/errors.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module Markdown
+    module Errors
+      # Base error class for Markdown errors
+      # Inherits from Coradoc::Error for unified error handling
+      class Error < Coradoc::Error
+      end
+
+      # Raised when Markdown parsing fails
+      class ParseError < Error
+      end
+
+      # Raised when Markdown serialization fails
+      class SerializationError < Error
+      end
+
+      # Raised when an unsupported Markdown feature is encountered
+      class UnsupportedFeatureError < Error
+      end
+
+      # Raised when Markdown-to-CoreModel transformation fails
+      class TransformationError < Error
+      end
+    end
+  end
+end

data/lib/coradoc/markdown/model/abbreviation.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module Markdown
+    # Abbreviation model representing an abbreviation definition.
+    #
+    # Kramdown syntax:
+    # `*[ABC]: A Big Corporation`
+    #
+    # When the abbreviation appears in the text, it will be wrapped
+    # with an <abbr> tag with the definition as the title.
+    #
+    # @example Abbreviation definition
+    #   abbr = Coradoc::Markdown::Abbreviation.new(
+    #     term: "ABC",
+    #     definition: "A Big Corporation"
+    #   )
+    #
+    class Abbreviation < Base
+      # The abbreviation term
+      attribute :term, :string
+
+      # The full definition/explanation
+      attribute :definition, :string
+    end
+  end
+end

data/lib/coradoc/markdown/model/attribute_list.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module Markdown
+    # Represents an Inline Attribute List (IAL) or Attribute List Definition (ALD)
+    #
+    # IAL syntax: {:.class #id key="value"}
+    # ALD syntax: {:name: #id .class key="value"}
+    #
+    # Examples:
+    #   {:.highlight} - adds class "highlight"
+    #   {#introduction} - sets id to "introduction"
+    #   {:key="value"} - sets attribute key="value"
+    #   {:name: #id .class} - defines ALD named "name"
+    #
+    class AttributeList < Base
+      attribute :id, :string
+      attribute :classes, :string, collection: true, default: []
+      attribute :attributes, :hash, default: {}
+      attribute :name, :string # For ALD - the reference name
+
+      # Parse an IAL string into an AttributeList
+      # @param str [String] The IAL string (e.g., '{:.class #id key="val"}')
+      # @return [AttributeList] Parsed attribute list
+      def self.parse(str)
+        return nil if str.nil? || str.empty?
+
+        # Remove surrounding braces
+        content = str.strip.gsub(/\A\{?:?|\}?\z/, '')
+
+        attr_list = new
+
+        # Check for ALD (has a name before colon)
+        if content =~ /\A(\w+):\s*/
+          attr_list.name = ::Regexp.last_match(1)
+          content = ::Regexp.last_match.post_match
+        end
+
+        # Parse the content
+        parse_attributes(content, attr_list)
+
+        attr_list
+      end
+
+      # Merge another AttributeList into this one
+      # @param other [AttributeList] The other attribute list to merge
+      # @return [AttributeList] self for chaining
+      def merge!(other)
+        return self unless other
+
+        self.id = other.id if other.id
+        self.classes = (classes + other.classes).uniq
+        self.attributes = attributes.merge(other.attributes)
+        self
+      end
+
+      # Create a merged copy
+      # @param other [AttributeList] The other attribute list to merge
+      # @return [AttributeList] New merged attribute list
+      def merge(other)
+        dup.merge!(other)
+      end
+
+      # Check if this has any attributes
+      # @return [Boolean]
+      def empty?
+        id.nil? && classes.empty? && attributes.empty?
+      end
+
+      # Convert to Markdown IAL syntax
+      # @return [String]
+      def to_md
+        return '' if empty?
+
+        parts = []
+        parts << "##{id}" if id
+        parts += classes.map { |c| ".#{c}" }
+        parts += attributes.map { |k, v| %(#{k}="#{v}") }
+
+        "{:#{parts.join(' ')}}"
+      end
+
+      def self.parse_attributes(content, attr_list)
+        # Use shared IalParser for consistent parsing
+        ParserUtil::IalParser.tokenize(content).each do |token|
+          case token[:type]
+          when :class
+            attr_list.classes << token[:value]
+          when :id
+            attr_list.id = token[:value]
+          when :attribute
+            attr_list.attributes[token[:key]] = token[:value]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/coradoc/markdown/model/base.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module Markdown
+    # Base class for all Markdown model objects.
+    #
+    # The Base class provides common functionality for all document model elements,
+    # including serialization support and tree traversal.
+    #
+    class Base < Lutaml::Model::Serializable
+      attribute :id, :string
+
+      # Attribute list for IAL (Inline Attribute List) support
+      # This allows attaching classes, id, and other attributes to elements
+      # Example: {:.highlight #intro data-role="main"}
+      attribute :attribute_list, :string
+
+      # Classes from IAL (for convenience)
+      attribute :classes, :string, collection: true
+
+      # Additional attributes from IAL
+      attribute :attributes, :hash, default: {}
+
+      # Visit pattern for traversing the document tree
+      def self.visit(element, &block)
+        return element if element.nil?
+
+        element = yield element, :pre
+        element = case element
+                  when self
+                    element.visit(&block)
+                  when Array
+                    element.map { |child| visit(child, &block) }.flatten.compact
+                  when Hash
+                    result = {}
+                    element.each { |k, v| result[k] = visit(v, &block) }
+                    result
+                  else
+                    element
+                  end
+        yield element, :post
+      end
+
+      def visit(&block)
+        self.class.attributes.each_key do |attr_name|
+          child = public_send(attr_name)
+          result = self.class.visit(child, &block)
+          public_send(:"#{attr_name}=", result) if result != child
+        end
+        self
+      end
+
+      # Serialize polymorphic content to Markdown string
+      def serialize_content(content)
+        case content
+        when Array
+          content.map { |elem| serialize_content(elem) }.join
+        when String
+          content
+        when nil
+          ''
+        else
+          if content.is_a?(Base)
+            content.to_md
+          else
+            raise ArgumentError,
+                  "Cannot serialize #{content.class.name} to Markdown. " \
+                  'Expected String or Base subclass.'
+          end
+        end
+      end
+
+      # Does a shallow attribute dump of the object
+      def to_h
+        self.class.attributes.keys.each_with_object({}) do |attribute, acc|
+          acc[attribute] = public_send(attribute)
+        end
+      end
+
+      # Serialize this model element to Markdown
+      def to_md
+        Coradoc::Markdown::Serializer.serialize(self)
+      end
+    end
+  end
+end

data/lib/coradoc/markdown/model/blockquote.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module Markdown
+    # Blockquote model representing a Markdown blockquote (> prefix).
+    #
+    # @example Create a blockquote
+    #   quote = Coradoc::Markdown::Blockquote.new(
+    #     content: "This is a quoted text."
+    #   )
+    #
+    class Blockquote < Base
+      attribute :content, :string
+
+      def initialize(content: '')
+        super()
+        @content = content
+      end
+    end
+  end
+end

data/lib/coradoc/markdown/model/code.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module Markdown
+    # Code model representing inline code (`code`).
+    #
+    class Code < Base
+      attribute :text, :string
+    end
+  end
+end

data/lib/coradoc/markdown/model/code_block.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module Markdown
+    # CodeBlock model representing a fenced code block.
+    #
+    # @example Create a code block
+    #   code = Coradoc::Markdown::CodeBlock.new(
+    #     language: "ruby",
+    #     code: "puts 'Hello World'"
+    #   )
+    #
+    class CodeBlock < Base
+      attribute :language, :string
+      attribute :code, :string
+
+      def initialize(language: nil, code: '')
+        super()
+        @language = language
+        @code = code
+      end
+    end
+  end
+end

data/lib/coradoc/markdown/model/definition_item.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module Markdown
+    # DefinitionItem model representing a single definition in a definition list.
+    #
+    # Each definition item contains the definition content and can have
+    # nested blocks (paragraphs, code blocks, lists, etc.)
+    #
+    # @example Simple definition
+    #   defn = Coradoc::Markdown::DefinitionItem.new(content: "A Markdown parser")
+    #
+    class DefinitionItem < Base
+      # The definition content (text or nested blocks)
+      attribute :content, :string
+
+      # Inline content can be an array of text/inline elements
+      attribute :inline_content, :string, collection: true
+
+      # Nested block content (paragraphs, code blocks, lists, etc.)
+      attribute :blocks, :string, collection: true
+    end
+  end
+end

data/lib/coradoc/markdown/model/definition_list.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module Markdown
+    # DefinitionList model representing a Kramdown definition list.
+    #
+    # Definition lists consist of terms followed by one or more definitions.
+    # The syntax uses `:` to start a definition.
+    #
+    # @example Simple definition list
+    #   list = Coradoc::Markdown::DefinitionList.new(
+    #     items: [
+    #       Coradoc::Markdown::DefinitionTerm.new(
+    #         text: "kramdown",
+    #         definitions: [
+    #           Coradoc::Markdown::DefinitionItem.new(content: "A Markdown parser")
+    #         ]
+    #       )
+    #     ]
+    #   )
+    #
+    # Syntax:
+    #   term
+    #   : definition content
+    #
+    #   multiple terms
+    #   : first definition
+    #   : second definition
+    #
+    class DefinitionList < Base
+      # Terms with their definitions
+      attribute :items, Coradoc::Markdown::DefinitionTerm, collection: true
+
+      # Serialize to Markdown
+      def to_md
+        items.map do |term|
+          term_text = term.text.to_s
+          defs = term.definitions.map do |defn|
+            content = defn.content.to_s
+            ": #{content}"
+          end.join("\n")
+          "#{term_text}\n#{defs}"
+        end.join("\n\n")
+      end
+    end
+  end
+end

data/lib/coradoc/markdown/model/definition_term.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module Markdown
+    # DefinitionTerm model representing a term in a definition list.
+    #
+    # A term can have multiple definitions and can span multiple lines.
+    # Terms can also have IAL attributes attached.
+    #
+    # @example Simple term
+    #   term = Coradoc::Markdown::DefinitionTerm.new(text: "kramdown")
+    #
+    class DefinitionTerm < Base
+      # The term text content
+      attribute :text, :string
+
+      # Definitions for this term
+      attribute :definitions, Coradoc::Markdown::DefinitionItem, collection: true, default: []
+    end
+  end
+end

data/lib/coradoc/markdown/model/document.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module Markdown
+    # Document model representing a Markdown document.
+    #
+    # The Document class is the main container for parsed Markdown content.
+    # It holds the document's blocks (headings, paragraphs, lists, etc.).
+    #
+    # @example Create a new document
+    #   doc = Coradoc::Markdown::Document.new(
+    #     blocks: [
+    #       Coradoc::Markdown::Heading.new(level: 1, text: "My Document"),
+    #       Coradoc::Markdown::Paragraph.new(text: "Hello World")
+    #     ]
+    #   )
+    #
+    class Document < Base
+      attribute :blocks, Coradoc::Markdown::Base, collection: true
+
+      # @param [Integer] index The index of the block to retrieve
+      # @return [Coradoc::Markdown::Base] The block at the specified index
+      def [](index)
+        blocks[index]
+      end
+
+      # @param [Integer] index The index of the block to set
+      # @param [Coradoc::Markdown::Base] value The block to set
+      def []=(index, value)
+        blocks[index] = value
+      end
+
+      # Create a document from an array of blocks
+      def self.from_ast(elements)
+        new(blocks: elements)
+      end
+    end
+  end
+end

data/lib/coradoc/markdown/model/emphasis.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module Markdown
+    # Emphasis model representing italic text (*text* or _text_).
+    #
+    class Emphasis < Base
+      attribute :text, :string
+    end
+  end
+end

data/lib/coradoc/markdown/model/extension.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module Markdown
+    # Represents a kramdown extension
+    #
+    # Extension syntax: {::extension_name options /}
+    # Common extensions:
+    #   {::toc} - table of contents
+    #   {::options key="value" /} - parser options
+    #   {::comment}content{:/} - comment
+    #   {::nomarkdown}content{:/} - raw HTML passthrough
+    #
+    class Extension < Base
+      attribute :name, :string
+      attribute :options, :hash, default: {}
+      attribute :content, :string  # For block extensions with content
+      attribute :body, :string     # Alias for content
+
+      # Known extension types
+      TYPES = {
+        toc: :toc,
+        options: :options,
+        comment: :comment,
+        nomarkdown: :nomarkdown,
+        ignore: :ignore,
+        if: :conditional,
+        endif: :conditional
+      }.freeze
+
+      # Create a TOC extension
+      # @param options [Hash] TOC options (levels, etc.)
+      # @return [Extension]
+      def self.toc(options = {})
+        new(name: :toc, options: options)
+      end
+
+      # Create an options extension
+      # @param options [Hash] Parser options
+      # @return [Extension]
+      def self.options(options = {})
+        new(name: :options, options: options)
+      end
+
+      # Create a comment extension
+      # @param content [String] Comment content
+      # @return [Extension]
+      def self.comment(content = '')
+        new(name: :comment, content: content)
+      end
+
+      # Create a nomarkdown extension (passthrough)
+      # @param content [String] Raw content to pass through
+      # @return [Extension]
+      def self.nomarkdown(content)
+        new(name: :nomarkdown, content: content)
+      end
+
+      # Check if this is a specific extension type
+      # @param type [Symbol] The extension type
+      # @return [Boolean]
+      def type?(type)
+        name.to_sym == type
+      end
+
+      # Check if this is a self-closing extension
+      # @return [Boolean]
+      def self_closing?
+        content.nil? || content.empty?
+      end
+
+      # Convert to Markdown
+      # @return [String]
+      def to_md
+        opts = options.empty? ? '' : " #{options_to_s}"
+        if self_closing?
+          "{::#{name}#{opts} /}"
+        else
+          "{::#{name}#{opts}}#{content}{:/}"
+        end
+      end
+
+      private
+
+      def options_to_s
+        options.map do |k, v|
+          %(#{k}="#{v}")
+        end.join(' ')
+      end
+    end
+  end
+end

data/lib/coradoc/markdown/model/footnote.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module Markdown
+    # Footnote model representing a footnote definition or reference.
+    #
+    # Kramdown syntax:
+    # - Reference: `[^1]` or `[^name]`
+    # - Definition: `[^1]: Footnote text`
+    #
+    # @example Footnote definition
+    #   fn = Coradoc::Markdown::Footnote.new(
+    #     id: "1",
+    #     content: "This is a footnote"
+    #   )
+    #
+    class Footnote < Base
+      # The footnote identifier (number or name)
+      attribute :id, :string
+
+      # The footnote content
+      attribute :content, :string
+
+      # Inline content (can be array of elements)
+      attribute :inline_content, :string, collection: true
+
+      # Reference back to where this footnote is used
+      attribute :backlink, :boolean, default: true
+    end
+  end
+end

data/lib/coradoc/markdown/model/footnote_reference.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module Markdown
+    # FootnoteReference model representing an inline footnote reference.
+    #
+    # Syntax: `[^name]` anywhere in text
+    #
+    # @example
+    #   ref = Coradoc::Markdown::FootnoteReference.new(id: "1")
+    #
+    class FootnoteReference < Base
+      # The footnote identifier
+      attribute :id, :string
+
+      # Serialize to Markdown
+      def to_md
+        "[^#{id}]"
+      end
+    end
+  end
+end

data/lib/coradoc/markdown/model/heading.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module Markdown
+    # Heading model representing a Markdown heading (# to ######).
+    #
+    # @example Create a heading
+    #   heading = Coradoc::Markdown::Heading.new(level: 1, text: "Title")
+    #
+    class Heading < Base
+      attribute :level, :integer, default: 1
+      attribute :text, :string
+
+      def initialize(level: 1, text: '')
+        super()
+        @level = level
+        @text = text
+      end
+
+      # Generate an auto ID from the heading text
+      #
+      # @return [String] A slugified version of the text suitable for use as an ID
+      # @example
+      #   Heading.new(text: "Hello World!").auto_id #=> "hello-world"
+      def auto_id
+        return '' if text.nil? || text.empty?
+
+        # Downcase, replace non-alphanumeric with hyphens, collapse multiple hyphens
+        slug = text.to_s
+                   .downcase
+                   .gsub(/[^a-z0-9]+/, '-')
+                   .gsub(/^-+|-+$/, '')
+        slug.empty? ? 'section' : slug
+      end
+
+      # Get the ID for this heading (uses explicit id if set, otherwise auto_id)
+      #
+      # @return [String] The ID to use for this heading
+      def heading_id
+        id || auto_id
+      end
+    end
+  end
+end

data/lib/coradoc/markdown/model/highlight.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+
+module Coradoc
+  module Markdown
+    # Represents highlighted text using == syntax (extended Markdown).
+    #
+    # Example: ==highlighted text==
+    #
+    class Highlight < Base
+      attribute :text, :string
+
+      def to_md
+        "==#{text}=="
+      end
+    end
+  end
+end