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

project_for_source, 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 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

  • project (String) —

    the project owning this file must be stored



118
119
120
121
122
123
124
125
126
127
128
129
130
131
 
# File 'lib/neruda/org_file.rb', line 118

def initialize(file_name, opts = {})
  file_name = nil if file_name == ''
  @file = file_name
  @html_file = nil
  @url = nil
  @project = opts.delete :project
  @options = opts
  build_html_file_and_url
  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



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

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.



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

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.



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

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.



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

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.



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

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.



46
47
48
 
# File 'lib/neruda/org_file.rb', line 46

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



60
61
62
 
# File 'lib/neruda/org_file.rb', line 60

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.



33
34
35
 
# File 'lib/neruda/org_file.rb', line 33

def notime
  @notime
end

#project ⇒ String (readonly)

Returns the project owning this document.

Returns:

  • (String) —

    the project owning this document.



74
75
76
 
# File 'lib/neruda/org_file.rb', line 74

def project
  @project
end

#subtitle ⇒ String (readonly)

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

Returns:

  • (String) —

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



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

def subtitle
  @subtitle
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.



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

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.



71
72
73
 
# File 'lib/neruda/org_file.rb', line 71

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



181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
 
# File 'lib/neruda/org_file.rb', line 181

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

  • %n

    the Neruda name and version

  • %N

    the Neruda name and version with a link to the project home on the name

  • %s

    the subtitle of the document

  • %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>~

rubocop:disable Metrics/MethodLength rubocop:disable Layout/LineLength

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



234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
 
# File 'lib/neruda/org_file.rb', line 234

def format(string)
  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', (Neruda::Config.settings['license'] || '').gsub(/\s+/, ' ').strip)
        .gsub('%n', "Neruda #{Neruda::VERSION}")
        .gsub('%N', "<a href=\"https://git.umaneti.net/neruda/about/\">Neruda</a> #{Neruda::VERSION}")
        .gsub('%s', @subtitle)
        .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



160
161
162
163
 
# File 'lib/neruda/org_file.rb', line 160

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) 


262
263
264
265
266
267
 
# File 'lib/neruda/org_file.rb', line 262

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