class Neruda::OrgFile

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.

Attributes

author[R]

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

@return [String] the author name

date[R]

@return [DateTime] the date and time of the current org document,

taken from the ~#+date:~ header.
excerpt[R]

@return [String] the description of this org document, taken from

the ~#+description:~ header.
file[R]

@return [String] the relative path to the source of this document.

html_file[R]

@return [String] the relative path to the generated html file of

this document.
keywords[R]

@return [Array] the keywords list of the current org document,

taken from the ~#+keywords:~ header.
lang[R]

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.

@return [String] the document lang

notime[R]

@return [Boolean] wether a time has been extracted from the

current org document ~#+date:~ header.
project[R]

@return [String] the project owning this document.

subtitle[R]

@return [String] the subtitle of the current org document, taken

from the ~#+subtitle:~ header.
title[R]

@return [String] the title of the current org document, taken from

the ~#+title:~ header.
url[R]

@return [String] the url of this document, build from the ~domain~

settings and the above {#html_file @html_file} attribute.

Public Class Methods

new(file_name, opts = {}) click to toggle source

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.

@example

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"

@param file_name [String] path to the corresponding Org file @param opts [Hash] optional data to initialize new Org file @option opts [String] title ('') the title of the new Org file @option opts [String] author (system user or '') the author of the

document

@option opts [Boolean] verbose (false) if the

{Neruda::OrgFileHtmlizer#publish publish} method should output
emacs process messages

@option opts [String] project the project owning this file

must be stored

@return [Neruda::OrgFile] the new instance of Neruda::OrgFile

# 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

Public Instance Methods

datestring(dateformat = :full, year: true) click to toggle source

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.

@param dateformat [Symbol] the format to use to convert DateTime

into String

@param year [Boolean] wether or not the ~:full~ format must

contain the year

@return [String] the document DateTime string representation

# 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) click to toggle source

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 {Neruda::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>~

@example

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

@return [String] the given ~string~ after replacement occurs rubocop:disable Metrics/MethodLength rubocop:disable Layout/LineLength

# 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() click to toggle source

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.

@example 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"

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

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

@example with no date header in the org file

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

@return [String] the document key

# 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() click to toggle source

Writes the current OrgFile content to the underlying file.

The intermediate parent folders are created if necessary.

@return [Integer] the length written (as returned by the

underlying ~IO.write~ method call)
# 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

Private Instance Methods

build_html_file_and_url() click to toggle source
# File lib/neruda/org_file.rb, line 271
def build_html_file_and_url
  return if @file.nil?
  @html_file = Neruda::OrgFile.target_for_source(
    @file, @project, with_public_folder: false
  )
  @url = "#{Neruda::Config.settings['domain']}/#{@html_file}"
end
init_empty_file() click to toggle source
# File lib/neruda/org_file.rb, line 279
    def init_empty_file
      @title = @options[:title] || ''
      @subtitle = ''
      @date = DateTime.now
      @notime = false
      @author = @options[:author] || Neruda::Config.settings['author']
      @keywords = []
      @lang = @options[:lang] || Neruda::Config.settings['lang']
      @excerpt = ''
      body = @options[:content] || ''
      @content = @options[:raw_content] || <<~ORG
        #+title: #{@title}
        #+date: <#{@date.strftime('%Y-%m-%d %a. %H:%M:%S')}>
        #+author: #{@author}
        #+language: #{@lang}

        #{body}
      ORG
    end