Skip to contents

Source Text

Source: R/class-text.R
class-text.Rd

Structure source text and its translations.

Usage

text(..., source_lang = language_source_get(), algorithm = algorithms())

is_text(x)

# S3 method for class 'Text'
format(x, ...)

# S3 method for class 'Text'
print(x, ...)

# S3 method for class 'Text'
c(...)

merge_texts(..., algorithm = algorithms())

as_text(x, ...)

# S3 method for class 'call'
as_text(x, loc = location(), algorithm = algorithms(), ...)

Arguments

...

Usage depends on the underlying function.

  • Any number of Location objects and/or named character strings for text() (in no preferred order).

  • Any number of Text objects for merge_texts() and S3 method c().

  • Further arguments passed to or from other methods for format(), print(), and as_text().

source_lang

A non-empty and non-NA character string. The language of the source text.

A language is usually a code (of two or three letters) for a native language name. While users retain full control over codes, it is best to use language codes stemming from well-known schemes such as IETF BCP 47, or ISO 639-1. Doing so maximizes portability and cross-compatibility between packages.

algorithm

A non-empty and non-NA character string equal to "sha1", or "utf8". The algorithm to use when hashing source information for identification purposes.

x

Any R object.

loc

A Location object.

Value

text(), c(), and as_text() return an R6 object of class Text.

is_text() returns a logical value.

format() returns a character vector.

print() returns argument x invisibly.

merge_texts() returns a list of (combined) Text objects. It can be empty if all underlying Text objects are empty.

Details

A Text object is a piece of source text that is extracted from R source scripts.

  • It (typically) has one or more Locations within a project.

  • It has zero or more translations.

The Text class structures this information and exposes a set of methods to manipulate it.

Combining Text Objects

c() can only combine Text objects having the same hash. This is equivalent to having the same algorithm, source_lang, and source_text. In that case, the underlying translations and Location objects are combined and a new object is returned. It throws an error if all Text objects are empty (they have no set source_lang).

merge_texts() is a generalized version of c() that handles any number of Text objects having possibly different hashes. It can be viewed as a vectorized version of c(). It silently ignores and drops all empty Text objects.

Coercion

as_text() is an S3 generic function that attempts to coerce its argument into a suitable Text object. as_text.call() is the method used by find_source() to coerce a call object to a Text object. While it can be used, it should be avoided most of the time. Users may extend it by defining their own methods.

Active bindings

hash

A non-empty and non-NA character string. A reproducible hash generated from source_lang and source_text, and by using the algorithm specified by algorithm. It is used as a unique identifier for the underlying Text object.

This is a read-only field. It is automatically updated whenever fields source_lang and/or algorithm are updated.

algorithm

A non-empty and non-NA character string equal to "sha1", or "utf8". The algorithm to use when hashing source information for identification purposes.

source_lang

A non-empty and non-NA character string. The language of the source text.

A language is usually a code (of two or three letters) for a native language name. While users retain full control over codes, it is best to use language codes stemming from well-known schemes such as IETF BCP 47, or ISO 639-1. Doing so maximizes portability and cross-compatibility between packages.

source_text

A non-empty and non-NA character string. The source text. This is a read-only field.

languages

A character vector. Registered language codes. This is a read-only field. Use methods below to update it.

translations

A named character vector. Registered translations of source_text, including the latter. Names correspond to languages. This is a read-only field. Use methods below to update it.

locations

A list of Location objects giving the location(s) of source_text in the underlying project. It can be empty. This is a read-only field. Use methods below to update it.

Methods

Public methods

Method new()

Create a Text object.

Usage

Text$new(algorithm = algorithms())

Arguments

algorithm

A non-empty and non-NA character string equal to "sha1", or "utf8". The algorithm to use when hashing source information for identification purposes.

Returns

An R6 object of class Text.

Examples

# Consider using text() instead.
txt <- Text$new()

Method get_translation()

Extract a translation, or the source text.

Usage

Text$get_translation(lang = "")

Arguments

lang

A non-empty and non-NA character string. The underlying language.

A language is usually a code (of two or three letters) for a native language name. While users retain full control over codes, it is best to use language codes stemming from well-known schemes such as IETF BCP 47, or ISO 639-1 to maximize portability and cross-compatibility.

Returns

A character string. NULL is returned if the requested translation is not available.

Examples

txt <- Text$new()
txt$set_translation("en", "Hello, world!")

txt$get_translation("en")  ## Outputs "Hello, world!"
txt$get_translation("fr")  ## Outputs NULL

Method set_translation()

Register a translation, or the source text.

Usage

Text$set_translation(lang = "", text = "")

Arguments

lang

A non-empty and non-NA character string. The underlying language.

A language is usually a code (of two or three letters) for a native language name. While users retain full control over codes, it is best to use language codes stemming from well-known schemes such as IETF BCP 47, or ISO 639-1 to maximize portability and cross-compatibility.

text

A non-empty and non-NA character string. A translation, or the source text.

Details

This method is also used to register source_lang and source_text before setting them as such. See Examples below.

Returns

A NULL, invisibly.

Examples

# Register a pair of source_lang and source_text.
txt <- Text$new()
txt$set_translation("en", "Hello, world!")
txt$source_lang <- "en"

Method set_translations()

Register one or more translations, and/or the source text.

Usage

Text$set_translations(...)

Arguments

...

Any number of named, non-empty, and non-NA character strings.

Details

This method can be viewed as a vectorized version of method set_translation().

Returns

A NULL, invisibly.

Examples

txt <- Text$new()
txt$set_translations(en = "Hello, world!", fr = "Bonjour, monde!")

Method set_locations()

Register one or more locations.

Usage

Text$set_locations(...)

Arguments

...

Any number of Location objects.

Details

This method calls merge_locations() to merge all values passed to ... together with previously registered Location objects. The underlying registered paths and/or ranges won't be duplicated.

Returns

A NULL, invisibly.

Examples

txt <- Text$new()
txt$set_locations(
  location("a", 1L, 2L, 3L, 4L),
  location("a", 1L, 2L, 3L, 4L),
  location("b", 5L, 6L, 7L, 8L))

Method rm_translation()

Remove a registered translation.

Usage

Text$rm_translation(lang = "")

Arguments

lang

A non-empty and non-NA character string identifying a translation to be removed.

Details

You cannot remove lang when it is registered as the current source_lang. You must update source_lang before doing so.

Returns

A NULL, invisibly.

Examples

txt <- Text$new()
txt$set_translations(en = "Hello, world!", fr = "Bonjour, monde!")
txt$source_lang <- "en"

# Remove source_lang and source_text.
txt$source_lang <- "fr"
txt$rm_translation("en")

Method rm_location()

Remove a registered location.

Usage

Text$rm_location(path = "")

Arguments

path

A non-empty and non-NA character string identifying a Location object to be removed.

Returns

A NULL, invisibly.

Examples

txt <- Text$new()
txt$set_locations(
  location("a", 1L, 2L, 3L, 4L),
  location("b", 5L, 6L, 7L, 8L))

txt$rm_location("a")

Examples

# Set source language.
language_source_set("en")

# Create Text objects.
txt1 <- text(
  location("a", 1L, 2L, 3L, 4L),
  location("a", 1L, 2L, 3L, 4L),
  location("b", 5L, 6L, 7L, 8L),
  location("c", c(9L, 10L), c(11L, 12L), c(13L, 14L), c(15L, 16L)),
  en = "Hello, world!",
  fr = "Bonjour, monde!",
  es = "¡Hola, mundo!")

txt2 <- text(
  location("a", 1L, 2L, 3L, 4L),
  en = "Hello, world!",
  fr = "Bonjour, monde!",
  es = "¡Hola, mundo!")

txt3 <- text(
  source_lang = "fr2",
  location("a", 5L, 6L, 7L, 8L),
  en  = "Hello, world!",
  fr2 = "Bonjour le monde!",
  es  = "¡Hola, mundo!")

is_text(txt1)

# Texts objects has a specific format.
# print() calls format() internally, as expected.
print(txt1)
print(txt2)
print(txt3)

# Combine Texts objects.
# c() throws an error if they do not have the same
# hash (same souce_text, source_lang, and algorithm).
c(txt1, txt2)

# Text objects with different hashes can be merged.
# This groups Text objects according to their hashes
# and calls c() on each group. It returns a list.
merge_texts(txt1, txt2, txt3)

# Objects can be coerced to a Text object with as_text(). Below is an
# example for call objects. This is for illustration purposes only,
# and the latter should not be used. This method is used internally by
# find_source().
cl  <- str2lang("translate('Hello, world!')")
loc <- location("example in class-text", 2L, 32L, 2L, 68L)
as_text(cl, loc)


## ------------------------------------------------
## Method `Text$new`
## ------------------------------------------------

# Consider using text() instead.
txt <- Text$new()

## ------------------------------------------------
## Method `Text$get_translation`
## ------------------------------------------------

txt <- Text$new()
txt$set_translation("en", "Hello, world!")

txt$get_translation("en")  ## Outputs "Hello, world!"
txt$get_translation("fr")  ## Outputs NULL

## ------------------------------------------------
## Method `Text$set_translation`
## ------------------------------------------------

# Register a pair of source_lang and source_text.
txt <- Text$new()
txt$set_translation("en", "Hello, world!")
txt$source_lang <- "en"

## ------------------------------------------------
## Method `Text$set_translations`
## ------------------------------------------------

txt <- Text$new()
txt$set_translations(en = "Hello, world!", fr = "Bonjour, monde!")

## ------------------------------------------------
## Method `Text$set_locations`
## ------------------------------------------------

txt <- Text$new()
txt$set_locations(
  location("a", 1L, 2L, 3L, 4L),
  location("a", 1L, 2L, 3L, 4L),
  location("b", 5L, 6L, 7L, 8L))

## ------------------------------------------------
## Method `Text$rm_translation`
## ------------------------------------------------

txt <- Text$new()
txt$set_translations(en = "Hello, world!", fr = "Bonjour, monde!")
txt$source_lang <- "en"

# Remove source_lang and source_text.
txt$source_lang <- "fr"
txt$rm_translation("en")

## ------------------------------------------------
## Method `Text$rm_location`
## ------------------------------------------------

txt <- Text$new()
txt$set_locations(
  location("a", 1L, 2L, 3L, 4L),
  location("b", 5L, 6L, 7L, 8L))

txt$rm_location("a")