Class: MetaHeader

Inherits:
Object
  • Object
show all
Defined in:
lib/metaheader.rb,
lib/metaheader/version.rb

Overview

Parser for metadata header in plain-text files

Examples:

mh = MetaHeader.parse '@hello world'
puts mh[:hello]

Constant Summary collapse

OPTIONAL =

Allow a tag to be omitted when validating in strict mode.

Object.new.freeze
REQUIRED =

Ensure a tag exists during validation.

Object.new.freeze
BOOLEAN =

The tag cannot hold a value beside true or false during validation.

Object.new.freeze
VALUE =

The tag must have a string value (non-boolean tag) during validation.

Object.new.freeze
SINGLELINE =

Don’t allow multiline values during validation.

Object.new.freeze
VERSION =

MetaHeader’s version

'2.0.1'.freeze

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize ⇒ MetaHeader

Construct a blank MetaHeader object



43
44
45
 
# File 'lib/metaheader.rb', line 43

def initialize
  @data = {}
end

Class Method Details

.from_file(path) ⇒ MetaHeader

Create a new instance from the contents of a file.

Parameters:

  • path (String) —

    path to the file to be read

Returns:



28
29
30
 
# File 'lib/metaheader.rb', line 28

def self.from_file(path)
  File.open(path) {|file| self.parse file }
end

.parse(input) ⇒ MetaHeader

Construct a MetaHeader object and parse every tags found in the input up to the first newline.

Parameters:

  • input (String, IO, StringIO)

Returns:



36
37
38
39
40
 
# File 'lib/metaheader.rb', line 36

def self.parse(input)
  mh = MetaHeader.new
  mh.parse input
  mh
end

Instance Method Details

#[](key, default = nil) ⇒ Object?

Returns the value of a tag by its name, or nil if not found.

Parameters:

  • key (Symbol) —

    tag name

  • default (Object) (defaults to: nil) —

    value to return if key doesn’t exist

Returns:

  • (Object, nil) 


73
74
75
76
77
78
79
 
# File 'lib/metaheader.rb', line 73

def [](key, default = nil)
  if tag = @data[key]
    tag.value
  else
    default
  end
end

#[]=(key, value) ⇒ Object

Replaces the value of a tag.

Parameters:

  • value —

    the new value

Returns:

  • (Object) —

    value

Raises:

  • (ArgumentError) 


84
85
86
87
88
89
 
# File 'lib/metaheader.rb', line 84

def []=(key, value)
  raise ArgumentError, 'value cannot be nil' if value.nil?

  @data[key] ||= Tag.new key
  @data[key].value = value
end

#alias(old, new = nil) ⇒ Object

Rename one or more tags.

Examples:

mh.alias :old, :new
mh.alias [:old1, :old2], :new
mh.alias old1: :new1, old2: :new2

Parameters:

  • old (Symbol, Array<Symbol>, Hash<Symbol, Symbol>)
  • new (Symbol) (defaults to: nil) —

    Ignored if old is a Hash



169
170
171
172
173
174
175
176
177
 
# File 'lib/metaheader.rb', line 169

def alias(old, new = nil)
  if old.is_a? Hash
    old.each {|k, v| self.alias k, v }
  else
    Array(old).each {|tag|
      @data[new] = delete tag if has? tag
    }
  end
end

#delete(tag) ⇒ Object

Removes a given tag from the list.

Parameters:

  • tag (Symbol) —

    the tag to remove



112
113
114
 
# File 'lib/metaheader.rb', line 112

def delete(tag)
  @data.delete tag
end

#empty? ⇒ Boolean

Whether any tags were found in the input.

Returns:

  • (Boolean) 


99
100
101
 
# File 'lib/metaheader.rb', line 99

def empty?
  @data.empty?
end

#has?(tag) ⇒ Boolean

Whether a tag was found in the input.

Parameters:

  • tag (Symbol) —

    the tag to lookup

Returns:

  • (Boolean) 


106
107
108
 
# File 'lib/metaheader.rb', line 106

def has?(tag)
  @data.has_key? tag
end

#inspect ⇒ String

Makes a human-readable representation of the current instance.

Returns:

  • (String) 


124
125
126
 
# File 'lib/metaheader.rb', line 124

def inspect
  "#<#{self.class} #{to_h}>"
end

#parse(input) ⇒ Integer

Parse every tags found in the input up to the first newline. data following the header.

Parameters:

  • input (String, IO, StringIO)

Returns:

  • (Integer) —

    Character position of the first content line in the input



51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
 
# File 'lib/metaheader.rb', line 51

def parse(input)
  if input.is_a? String
    input = StringIO.new input.encode universal_newline: true
  end

  @last_tag = nil
  @empty_lines = 0

  content_offset = 0
  input.each_line do |line|
    full_line_size = line.size # parse_line can trim the line
    continue = parse_line line
    content_offset += full_line_size if continue || line.empty?
    break unless continue
  end
  content_offset
end

#size ⇒ Integer

Returns how many tags were found in the input.

Returns:

  • (Integer) 


93
94
95
 
# File 'lib/metaheader.rb', line 93

def size
  @data.size
end

#to_h ⇒ Hash<Symbol, Object>

Make a hash from the parsed data

Returns:

  • (Hash<Symbol, Object>) 


118
119
120
 
# File 'lib/metaheader.rb', line 118

def to_h
  Hash[@data.map {|name, tag| [name, tag.value] }]
end

#validate(rules, strict = false) ⇒ Array<String>

Validates parsed data according to a custom set of rules. A rule can be one of the predefined constants, a regex, a proc or a method (returing nil if the tag is valid or an error string otherwise).

Examples:

mh = MetaHeader.new "@hello world\n@chunky bacon"
mh.validate \
  hello: [MetaHeader::REQUIRED, MetaHeader::SINGLELINE, /\d/],
  chunky: proc {|value| 'not bacon' unless value == 'bacon' }

Parameters:

  • rules (Hash) —

    :tag_name => rule or [rule1, rule2, …]

  • strict (Boolean) (defaults to: false) —

    Whether to report unknown tags as errors

Returns:

  • (Array<String>) —

    List of error messasges

See Also:



144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
 
# File 'lib/metaheader.rb', line 144

def validate(rules, strict = false)
  errors = []

  if strict
    @data.each {|key, tag|
      errors << "unknown tag '%s'" % tag.name unless rules.has_key? key
    }
  end

  rules.each_pair {|key, rule|
    if key_error = validate_key(key, rule)
      errors << key_error
    end
  }

  errors
end