Class: RichText::Document

Inherits:
Object
  • Object
show all
Defined in:
lib/richtext/document.rb,
lib/richtext/document/entry.rb

Defined Under Namespace

Classes: Entry

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(arg = '') ⇒ Document

Initialize

Create a new RichText Document, either from a string or from an existing ducument. That feature is particularly useful when converting between formats.

When given a string or a RichText Document of the same class no parsing is performed. Only when given a document of a different subclass will the parser need to be run parsed. Note that the document(s) may already be in

parsed form, in which case no further parsing is performed. See #base for more details.



15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
 
# File 'lib/richtext/document.rb', line 15

def initialize arg = ''
  @base, @raw = if self.class == arg.class
    arg.parsed? ?
      [arg.base, nil] :
      [nil, arg.raw]
  elsif Document === arg
    # For any other RichText object we take the base node
    [arg.base, nil]
  elsif Entry === arg
    # Also accept an Entry which will be used as the
    # document base
    [arg, nil]
  else
    [nil, arg.to_s]
  end
end

Class Method Details

.from(doc) ⇒ Object

From

Convenience method for instansiating one RichText object from another. The methods only purpose is to make that intent more clear, and to make the creation from another RichText object explicit.



171
172
173
174
175
176
177
178
 
# File 'lib/richtext/document.rb', line 171

def self.from doc
  unless Document === doc
    raise TypeError, 
        "Can only create a #{self.name} from other RichText objects"
  end
      
  self.new doc
end

.parse(base, string) ⇒ Object

Parse

Document type specific method for parsing a string and turning it into a tree of entry nodes. This method is intended to be overridden when the Document is subclassed. The default implementation just creates a top level Entry containing the given string.



149
150
151
 
# File 'lib/richtext/document.rb', line 149

def self.parse base, string
  base[:text] = string
end

.render(base) ⇒ Object

Render

Document type specific method for rendering a tree of entry nodes. This method is intended to be overridden when the Document is subclassed. The default implementation just concatenates the text entries into.



160
161
162
 
# File 'lib/richtext/document.rb', line 160

def self.render base
  base.to_s
end

Instance Method Details

#+(other) ⇒ Object

Add (+)

Add this RichText to another.



57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
 
# File 'lib/richtext/document.rb', line 57

def + other
  # If the other object is of the same class, and neither
  # one of the texts have been parsed, we can concatenate
  # the raw inputs together
  if other.class == self.class && !parsed? && !other.parsed?
    return self.class.new (@raw + other.raw)
  end
  
  # Same root class
  if Document === other
    return self.class.new (base + other.base)
  end
  
  unless other.respond_to?(:to_s)
    raise TypeError,
      "cannot add #{other.class.name} to #{self.class.name}"
  end
  
  # Assume that the input is a raw string of the same
  # class as the current RichText object and wrap it
  # before adding it
  self + self.class.new(other)
end

#append(string, **attributes) ⇒ Object 



82
83
84
85
86
 
# File 'lib/richtext/document.rb', line 82

def append string, **attributes
  node = Entry.new(string, **attributes)
  base.add node
  node
end

#base ⇒ Object Also known as: root

Base

Getter for the base node. If the raw input has not yet been parsed that will happen first, before the base node is returned.



94
95
96
97
98
99
100
101
102
 
# File 'lib/richtext/document.rb', line 94

def base
  unless @base
    @base = Entry.new
    self.class.parse @base, @raw
    @raw  = nil # Free the cached string
  end
  
  @base
end

#each_node(&block) ⇒ Object Also known as: each_entry

Each Node

Iterate over all Entry nodes in the document tree.



135
136
137
 
# File 'lib/richtext/document.rb', line 135

def each_node &block
  base.each(&block)
end

#parsed? ⇒ Boolean

Parsed?

Returns true if the raw input has been parsed and the internal representation is now a tree of nodes.

Returns:

  • (Boolean) 


121
122
123
 
# File 'lib/richtext/document.rb', line 121

def parsed?
  @raw.nil?
end

#to_s(&block) ⇒ Object

To String

Use the static implementation of .render to convert the document back into a string. If the document was never parsed (and is unchanged) the origninal string is just returned.

If a block is given it will be used in place of .render to format the node tree.



42
43
44
45
46
47
48
49
50
 
# File 'lib/richtext/document.rb', line 42

def to_s &block
  if block_given?
    base.to_s(&block)
  elsif parsed? || should_parse?
    self.class.render base
  else
    @raw
  end
end