Class: Neruda::OrgFile

Inherits:
Object
  • Object
show all
Extended by:
OrgFileClassMethods
Includes:
OrgFileExtracter, OrgFileHtmlizer
Defined in:
lib/neruda/org_file.rb

Overview

Handles org files.

This class is responsible for reading or writing existing or new org files, and formating their content to be used on the generated website.

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from OrgFileClassMethods

html_file_with_domain, slug, source_for_target, target_for_source

Methods included from OrgFileHtmlizer

#publish

Constructor Details

#initialize(file_name, opts = {}) ⇒ Neruda::OrgFile

Prepares the file named by ~file_name~ for read and write

operations.

If the file ~file_name~ does not exist, the new instance may be populated by data given in the ~opts~ parameter.

Examples:

File.exist? './test.org'
=> true
o = Neruda::OrgFile.new('./test.org')
=> #<Neruda::OrgFile @file='./test.org'...>
o.title
=> "This is an existing test file"
File.exist? '/tmp/does_not_exist.org'
=> false
o = Neruda::OrgFile.new('/tmp/does_not_exist.org')
=> #<Neruda::OrgFile @file='/tmp/does_not_exist.org'...>
o.title
=> ""
File.exist? '/tmp/other.org'
=> false
o = Neruda::OrgFile.new('/tmp/other.org', title: 'New file')
=> #<Neruda::OrgFile @file='/tmp/other.org'...>
o.title
=> "New file"

Parameters:

  • file_name (String) —

    path to the corresponding org mode file

  • opts (Hash) (defaults to: {}) —

    optional data to initialize new org file

Options Hash (opts):

  • title (String) — default: '' —

    the title of the new org file

  • author (String) — default: system user or '' —

    the author of the document

  • verbose (Boolean) — default: false —

    if the publish method should output emacs process messages



108
109
110
111
112
113
114
115
116
117
118
119
 
# File 'lib/neruda/org_file.rb', line 108

def initialize(file_name, opts = {})
  file_name = nil if file_name == ''
  @file = file_name
  @html_file = Neruda::OrgFile.html_file @file
  @url = Neruda::OrgFile.html_file_with_domain @file
  @options = opts
  if @file && File.exist?(@file)
    extract_data
  else
    init_empty_file
  end
end

Instance Attribute Details

#author ⇒ String (readonly)

The author of the current org document, taken from the ~#+author:~

header.

If the current document doesn’t have any authorship information, the one from the ~config.yml~ file will be used instead

Returns:

  • (String) —

    the author name



37
38
39
 
# File 'lib/neruda/org_file.rb', line 37

def author
  @author
end

#date ⇒ DateTime (readonly)

Returns the date and time of the current org document, taken from the ~#+date:~ header.

Returns:

  • (DateTime) —

    the date and time of the current org document, taken from the ~#+date:~ header.



24
25
26
 
# File 'lib/neruda/org_file.rb', line 24

def date
  @date
end

#excerpt ⇒ String (readonly)

Returns the description of this org document, taken from the ~#+description:~ header.

Returns:

  • (String) —

    the description of this org document, taken from the ~#+description:~ header.



66
67
68
 
# File 'lib/neruda/org_file.rb', line 66

def excerpt
  @excerpt
end

#file ⇒ String (readonly)

Returns the relative path to the source of this document.

Returns:

  • (String) —

    the relative path to the source of this document.



54
55
56
 
# File 'lib/neruda/org_file.rb', line 54

def file
  @file
end

#html_file ⇒ String (readonly)

Returns the relative path to the generated html file of this document.

Returns:

  • (String) —

    the relative path to the generated html file of this document.



58
59
60
 
# File 'lib/neruda/org_file.rb', line 58

def html_file
  @html_file
end

#keywords ⇒ Array (readonly)

Returns the keywords list of the current org document, taken from the ~#+keywords:~ header.

Returns:

  • (Array) —

    the keywords list of the current org document, taken from the ~#+keywords:~ header.



41
42
43
 
# File 'lib/neruda/org_file.rb', line 41

def keywords
  @keywords
end

#lang ⇒ String (readonly)

The locale of the current org document, taken from the

~#+language:~ header.

If the current document doesn’t have any language information, the one from the ~config.yml~ file will be used instead, or “en” by default.

Returns:

  • (String) —

    the document lang



51
52
53
 
# File 'lib/neruda/org_file.rb', line 51

def lang
  @lang
end

#notime ⇒ Boolean (readonly)

Returns wether a time has been extracted from the current org document ~#+date:~ header.

Returns:

  • (Boolean) —

    wether a time has been extracted from the current org document ~#+date:~ header.



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

def notime
  @notime
end

#title ⇒ String (readonly)

Returns the title of the current org document, taken from the ~#+title:~ header.

Returns:

  • (String) —

    the title of the current org document, taken from the ~#+title:~ header.



20
21
22
 
# File 'lib/neruda/org_file.rb', line 20

def title
  @title
end

#url ⇒ String (readonly)

Returns the url of this document, build from the ~domain~ settings and the above @html_file attribute.

Returns:

  • (String) —

    the url of this document, build from the ~domain~ settings and the above @html_file attribute.



62
63
64
 
# File 'lib/neruda/org_file.rb', line 62

def url
  @url
end

Instance Method Details

#datestring(dateformat = :full, year = true) ⇒ String

Returns the current OrgFile instance DateTime as a String.

This method accepts three values for the ~dateformat~ parameter:

  • ~:full~ (or ~:long~)

    outputs a complete date and time

    representation, localized through R18n;

  • ~:short~

    outputs a short date representation (without time),

    localized with R18n;

  • ~:rfc3339~

    outputs the RFC 3339 date and time representation,

    used in atom feed.

Parameters:

  • dateformat (Symbol) (defaults to: :full) —

    the format to use to convert DateTime into String

  • year (Boolean) (defaults to: true) —

    wether or not the ~:full~ format must contain the year

Returns:

  • (String) —

    the document DateTime string representation



169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
 
# File 'lib/neruda/org_file.rb', line 169

def datestring(dateformat = :full, year = true)
  return '' if @date.nil?
  return R18n.l @date.to_date if dateformat == :short
  return @date.rfc3339 if dateformat == :rfc3339
  locale = R18n.get.locale
  long_fmt = R18n.t.neruda.index.full_date_format(
    date: locale.format_date_full(@date, year)
  )
  unless @notime
    long_fmt = R18n.t.neruda.index.full_date_with_time_format(
      date: long_fmt, time: locale.time_format.delete('_').strip
    )
  end
  locale.strftime(@date, long_fmt)
end

#format(string) ⇒ String

Formats given ~string~ with values of the current OrgFile.

This method expects to find percent-tags in the given ~string~ and replace them by their corresponding value.

*** Format:

  • %a

    the raw author name

  • %A

    the HTML rendering of the author name, equivalent to ~<span class=“author”>%a</span>~

  • %d

    the ~:short~ date HTML representation, equivalent to ~<time datetime=“%I”>%i</time>~

  • %D

    the ~:full~ date and time HTML representation

  • %i

    the raw ~:short~ date and time

  • %I

    the raw ~:rfc3339~ date and time

  • %k

    the keywords separated by a comma

  • %K

    the HTML list rendering of the keywords

  • %l

    the lang of the document

  • %L

    the license information, taken from the Config#settings

  • %t

    the title of the document

  • %u

    the web path to the related published HTML document

  • %x

    the raw description (eXcerpt)

  • %X

    the description, enclosed in an HTML ~p~ tag, equivalent to ~<p>%x</p>~

Examples:

org_file.format("Article written by %a the %d")
=> "Article written by Alice Smith the Wednesday 3rd July"

Returns:

  • (String) —

    the given ~string~ after replacement occurs



216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
 
# File 'lib/neruda/org_file.rb', line 216

def format(string)
  license = Neruda::Config.settings['license'] || ''
  string.gsub('%a', @author)
        .gsub('%A', author_to_html)
        .gsub('%d', date_to_html(:short))
        .gsub('%D', date_to_html)
        .gsub('%i', datestring(:short))
        .gsub('%I', datestring(:rfc3339))
        .gsub('%k', @keywords.join(', '))
        .gsub('%K', keywords_to_html)
        .gsub('%l', @lang)
        .gsub('%L', license.gsub(/\s+/, ' ').strip)
        .gsub('%t', @title)
        .gsub('%u', @html_file)
        .gsub('%x', @excerpt)
        .gsub('%X', "<p>#{@excerpt}</p>")
end

#timekey ⇒ String

Returns a String representation of the document date, which aims

to be used to sort several OrgFiles.

The format used for the key is ~%Y%m%d%H%M%S~. If the current OrgFile instance does not have a date, this mehod return ~00000000000000~. If the current OrgFile instance does not have time information, the date is padded with zeros.

Examples:

with the org header ~#+date: <2019-07-03 Wed 20:52:49>~

org_file.date
=> #<DateTime: 2019-07-03T20:52:49+02:00...>
org_file.timekey
=> "20190703205349"

with the org header ~#+date: <2019-07-03 Wed>~

org_file.date
=> #<DateTime: 2019-07-03T00:00:00+02:00...>
org_file.timekey
=> "20190703000000"

with no date header in the org file

org_file.date
=> nil
org_file.timekey
=> "00000000000000"

Returns:

  • (String) —

    the document key



148
149
150
151
 
# File 'lib/neruda/org_file.rb', line 148

def timekey
  return '00000000000000' if @date.nil?
  @date.strftime('%Y%m%d%H%M%S')
end

#write ⇒ Integer

Writes the current OrgFile content to the underlying file.

The intermediate parent folders are created if necessary.

Returns:

  • (Integer) —

    the length written (as returned by the underlying ~IO.write~ method call)

Raises:

  • (TypeError) 


240
241
242
243
244
245
 
# File 'lib/neruda/org_file.rb', line 240

def write
  raise TypeError, 'no conversion from nil file name to path.' if @file.nil?
  file_dir = File.dirname @file
  FileUtils.mkdir_p file_dir unless Dir.exist? file_dir
  IO.write @file, @content
end