# Class: YARD::I18n::PotGenerator

Inherits:
  Object
  - Object
  - YARD::I18n::PotGenerator
  show all

Defined in:
  lib/yard/i18n/pot_generator.rb

## Overview

The `PotGenerator` generates POT format string from CodeObjects::Base and CodeObjects::ExtraFileObject.

## POT and PO

POT is an acronym for “Portable Object Template”. POT is a template file to create PO file. The extension for POT is “.pot”. PO file is an acronym for “Portable Object”. PO file has many parts of message ID (msgid) that is translation target message and message string (msgstr) that is translated message of message ID. If you want to translate “Hello” in English into “Bonjour” in French, “Hello” is the msgid ID and “Bonjour” is msgstr. The extension for PO is “.po”.

## How to extract msgids

The `PotGenerator` has two parse methods:

- #parse_objects for CodeObjects::Base

- #parse_files for CodeObjects::ExtraFileObject

#parse_objects extracts msgids from docstring and tags of CodeObjects::Base objects. The docstring of CodeObjects::Base object is parsed and a paragraph is extracted as a msgid. Tag name and tag text are extracted as msgids from a tag.

#parse_files extracts msgids from CodeObjects::ExtraFileObject objects. The file content of CodeObjects::ExtraFileObject object is parsed and a paragraph is extracted as a msgid.

## Usage

To create a .pot file by `PotGenerator`, instantiate a `PotGenerator` with a relative working directory path from a directory path that has created .pot file, parse CodeObjects::Base objects and CodeObjects::ExtraFileObject objects, generate a POT and write the generated POT to a .pot file. The relative working directory path is “..” when the working directory path is “.” and the POT is wrote into “po/yard.pot”.

#### Examples:

#####

Generate a .pot file

    po_file_path = "po/yard.pot"
    po_file_directory_pathname = Pathname.new(po_file_path).directory)
    working_directory_pathname = Pathname.new(".")
    relative_base_path = working_directory_pathname.relative_path_from(po_file_directory_pathname).to_s
    # relative_base_path -> ".."
    generator = YARD::I18n::PotGenerator.new(relative_base_path)
    generator.parse_objects(objects)
    generator.parse_files(files)
    pot = generator.generate
    po_file_directory_pathname.mkpath
    File.open(po_file_path, "w") do |pot_file|
      pot_file.print(pot)
    end

See Also:

- GNU gettext manual about details of PO file

Since:

- 0.8.0

## Instance Attribute Summary collapse

- #messages ⇒ Messages readonly

  Extracted messages.

## Instance Method Summary collapse

- #generate ⇒ String

  Generates POT from `@messages`.

- #initialize(relative_base_path) ⇒ PotGenerator constructor

  Creates a POT generator that uses `relative_base_path` to generate locations for a msgid.

- #parse_files(files) ⇒ void

  Parses CodeObjects::ExtraFileObject objects and stores extracted msgids into #messages.

- #parse_objects(objects) ⇒ void

  Parses CodeObjects::Base objects and stores extracted msgids into #messages.

## Constructor Details

### #initialize(relative_base_path) ⇒ `PotGenerator`

Creates a POT generator that uses `relative_base_path` to generate locations for a msgid. `relative_base_path` is prepended to all locations.

Parameters:

- relative_base_path (`String`) —

  a relative working directory path from a directory path that has created .pot file.

Since:

- 0.8.0

    79
    80
    81
    82
    83

    # File 'lib/yard/i18n/pot_generator.rb', line 79

    def initialize(relative_base_path)
      @relative_base_path = relative_base_path
      @extracted_objects = {}
      @messages = Messages.new
    end

## Instance Attribute Details

### #messages ⇒ `Messages` (readonly)

Extracted messages.

Returns:

- (`Messages`)

Since:

- 0.8.1

    70
    71
    72

    # File 'lib/yard/i18n/pot_generator.rb', line 70

    def messages
      @messages
    end

## Instance Method Details

### #generate ⇒ `String`

Generates POT from `@messages`.

One PO file entry is generated from a `Message` in `@messages`.

Locations of the `Message` are used to generate the reference line that is started with “#: ”. `relative_base_path` passed when the generator is created is prepended to each path in location.

Comments of the `Message` are used to generate the translator-comment line that is started with “# ”.

Returns:

- (`String`) —

  POT format string

Since:

- 0.8.0

    122
    123
    124
    125
    126
    127
    128
    129
    130
    131
    132

    # File 'lib/yard/i18n/pot_generator.rb', line 122

    def generate
      pot = String.new(header)
      sorted_messages = @messages.sort_by do |message|
        sorted_locations = message.locations.sort
        sorted_locations.first || []
      end
      sorted_messages.each do |message|
        generate_message(pot, message)
      end
      pot
    end

### #parse_files(files) ⇒ `void`

This method returns an undefined value.

Parses CodeObjects::ExtraFileObject objects and stores extracted msgids into #messages.

Parameters:

- files (`Array<CodeObjects::ExtraFileObject>`) —

  a list of CodeObjects::ExtraFileObject objects to be parsed.

Since:

- 0.8.0

    103
    104
    105
    106
    107

    # File 'lib/yard/i18n/pot_generator.rb', line 103

    def parse_files(files)
      files.each do |file|
        extract_paragraphs(file)
      end
    end

### #parse_objects(objects) ⇒ `void`

This method returns an undefined value.

Parses CodeObjects::Base objects and stores extracted msgids into #messages

Parameters:

- objects (`Array<CodeObjects::Base>`) —

  a list of CodeObjects::Base to be parsed.

Since:

- 0.8.0

    91
    92
    93
    94
    95

    # File 'lib/yard/i18n/pot_generator.rb', line 91

    def parse_objects(objects)
      objects.each do |object|
        extract_documents(object)
      end
    end