stres

README

stres - Android Studio string resources in Go

A simple and easy-to-use library to import and export string resources into your Go applications just like you would do in Android Studio. Useful to separate business logic from UI texts or to handle string translations.

Table of contents

• References
• Prerequisites
• Installing
  • Install module
  • Import in your project

• Documentation
  • Types
    • Plural
    • PluralItem
    • Item
    • StringArray
    • String
    • Nesting
  • CreateResourceFile
  • DeleteResourceFile
  • LoadValues
  • SetResourceType
  • NewString
  • NewStringArray
  • NewQuantityString
  • SetFewThreshold
  • GetString
  • GetArrayString
  • GetQuantityString
• Contributors

References

• Android Studio string resources
• CHANGELOG

Back to top

Prerequisites

• Make sure you have at least installed Go v1.17.

Back to top

Installing

Install module

go get github.com/Vinetwigs/stres

Back to top

Import in your project

import("github.com/Vinetwigs/stres")

Back to top

Documentation

Types

Plural

type Plural struct {
	XMLName xml.Name      `xml:"plurals" json:"plurals" yaml:"plurals" toml:"plurals" watson:"plurals" msgpack:"plurals"`
	Name    string        `xml:"name,attr" json:"name" yaml:"name" toml:"name" watson:"name" msgpack:"name"`
	Items   []*PluralItem `xml:"item" json:"items" yaml:"items,flow" toml:"items,multiline" watson:"items" msgpack:"items,as_array"`
}

Back to top

PluralItem

type PluralItem struct {
	XMLName  xml.Name `xml:"item" json:"item" yaml:"item" toml:"item" watson:"item" msgpack:"item"`
	Quantity string   `xml:"quantity,attr" json:"quantity" yaml:"quantity" toml:"quantity" watson:"quantity" msgpack:"quantity"`
	Value    string   `xml:",innerxml" json:"value" yaml:"value" toml:"value" watson:"value" msgpack:"value"`
}

Back to top

Item

type Item struct {
	XMLName xml.Name `xml:"item" json:"item" yaml:"item" toml:"item" watson:"item" msgpack:"item"`
	Value   string   `xml:",innerxml" json:"value" yaml:"value" toml:"value" watson:"value" msgpack:"value"`
}

Back to top

StringArray

type StringArray struct {
	XMLName xml.Name `xml:"string-array" json:"string-array" yaml:"string-array" toml:"string-array" watson:"string-array" msgpack:"string-array"`
	Name    string   `xml:"name,attr" json:"name" yaml:"name" toml:"name" watson:"name" msgpack:"name"`
	Items   []*Item  `xml:"item" json:"items" yaml:"items,flow" toml:"items,multiline" watson:"items" msgpack:"items,as_array" `
}

Back to top

String

type String struct {
	XMLName xml.Name `xml:"string" json:"string" yaml:"string" toml:"string" watson:"string" msgpack:"string"`
	Name    string   `xml:"name,attr" json:"name" yaml:"name" toml:"name" watson:"name" msgpack:"name"`
	Value   string   `xml:",innerxml" json:"value" yaml:"value" toml:"value" watson:"value" msgpack:"value"`
}

Back to top

Nesting

type Nesting struct {
	XMLName      xml.Name       `xml:"resources" json:"resources" yaml:"resources" toml:"resources" watson:"resources" msgpack:"resources"`
	Strings      []*String      `xml:"string" json:"string" yaml:"string,flow" toml:"string,multiline" watson:"string" msgpack:"string,as_array"`
	StringsArray []*StringArray `xml:"string-array" json:"string-array" yaml:"string-array,flow" toml:"string-array,multiline" watson:"string-array" msgpack:"string-array,as_array"`
	Plurals      []*Plural      `xml:"plurals" json:"plurals" yaml:"plurals,flow" toml:"plurals,multiline" watson:"plurals" msgpack:"plurals,as_array"`
}

Back to top

CreateResourceFile

Creates strings resource file in "strings" directory, throws an error otherwise. Takes a FileType parameter to specify strings file format.

file, err := stres.CreateXMLFile()

Parameter	Type	Description
t	types.FileType	enum value to specify file format

Back to top

DeleteResourceFile

Deletes resource file if exists, throws an error otherwise. Uses setted resource file extension.

err := stres.DeleteXMLFile()

Back to top

LoadValues

Loads values from strings file into internal dictionaries. Needs to be invoked only one time (but before getting strings values).Takes a FileType parameter to specify strings file format.

err := stres.LoadValues()

Back to top

Parameter	Type	Description
t	types.FileType	enum value to specify file format

SetResourceType

Used to specify string file extension. If t is a wrong FileType, sets resource type to XML by default.

stres.SetResourceType(stres.WATSON)

Parameter	Type	Description
t	types.FileType	enum value to specify file format

Back to top

NewString

Adds a new string resource to resource file. Throws an error if the chosen name is already inserted or it is an empty string. Used for programmatic insertion (manual insertion recommended).

String, err := stres.NewString("name", "value")

Parameter	Type	Description
name	string	unique name to identify the string
value	string	string to associate to the given name

Returns String instance and error.

Back to top

NewStringArray

Adds a new string-array resource to resource file. Throws an error if the chosen name is already inserted or it is an empty string. Used for programmatic insertion (manual insertion recommended).

strArr, err := stres.NewStringArray("name", []string{"value1","value2",...})

Parameter	Type	Description
name	string	unique name to identify the string
values	[]string	array of strings to associate to the given name

Returns StringArray instance and error.

Back to top

NewQuantityString

Adds a new quantity string resource to resource file. Throws an error if the chosen name is already inserted or it is an empty string. The function uses only the first 5 values in the array. The first value is assigned to "zero" quantity. The second value is assigned to "one" quantity. The third value is assigned to "two" quantity. The fourth value is assigned to "few" quantity. The fifth value is assigned to "more" quantity. Used for programmatic insertion (manual insertion recommended).

qntStr, err := stres.NewQuantityString("name", []string{"zero","one", "two", ...})

Parameter	Type	Description
name	string	unique name to identify the string
values	[]string	array of strings for quantities to associate to the given name

Returns Plural instance and error.

Back to top

SetFewThreshold

Sets the threshold for "few" values in quantity strings.When getting quantity strings values, the function checks if the given count is less OR EQUAL to this value.(default value: 20)

stres.SetFewThreshold(25)

Parameter	Type	Description
value	int	new value for 'few' threshold

Returns Plural instance and error.

Back to top

GetString

Returns the string resource's value with the given name. If not exists, returns empty string.

str := GetString("name")

Parameter	Type	Description
name	string	unique name given to the corresponding string

Returns a string.

Back to top

GetArrayString

Returns the string-array resource's values with the given name. If not exists, returns nil.

strArr := GetStringArray("name")

Parameter	Type	Description
name	string	unique name given to the corresponding string-array

Returns an array of strings.

Back to top

GetQuantityString

Returns the quantity string resource's corresponding string value based on the value of the given count parameter. If the plural is not found, returns an empty string.

strArr := GetQuantityString("name", 10)

Parameter	Type	Description
name	string	unique name to identify the string
count	int	quantity to fetch the corresponding string

Returns a string.

Back to top

Contributors

Documentation

Index

• Constants
• Variables
• func CreateResourceFile(t types.FileType) (*os.File, error)
• func DeleteResourceFile() error
• func GetArrayString(name string) []string
• func GetQuantityString(name string, count int) string
• func GetString(name string) string
• func LoadValues(t types.FileType) error
• func NewQuantityString(name string, values []string) (types.Plural, error)
• func NewString(name, value string) (types.String, error)
• func NewStringArray(name string, values []string) (types.StringArray, error)
• func SetFewThreshold(value int)
• func SetResourceType(t types.FileType)

Constants

const (
	XML     types.FileType = "xml"
	YAML    types.FileType = "yml"
	JSON    types.FileType = "json"
	TOML    types.FileType = "toml"
	WATSON  types.FileType = "watson"
	MSGPACK types.FileType = "msgpack"
)

Variables

var (
	ErrorEmptyStringName         error = errors.New("stres: string name can't be empty")
	ErrorEmptyStringArrayName    error = errors.New("stres: string-array name can't be empty")
	ErrorEmptyQuantityStringName error = errors.New("stres: quantity string name can't be empty")

	ErrorDuplicateStringName         error = errors.New("stres: string name already inserted")
	ErrorDuplicateStringArrayName    error = errors.New("stres: string-array name already inserted")
	ErrorDuplicateQuantityStringName error = errors.New("stres: quantity string name already inserted")

	ErrorQuantityStringPluralNotFound error = errors.New("stres: plural not found for the given quantity")

	ErrorQuantityStringEmptyValues error = errors.New("stres: provided empty array to quantity string creationg")
)

Functions

func CreateResourceFile

func CreateResourceFile(t types.FileType) (*os.File, error)

Creates strings resource file in "strings" directory, throws an error otherwise. Takes a FileType parameter to specify strings file format.

func DeleteResourceFile

func DeleteResourceFile() error

Deletes resource file if exists, throws an error otherwise. Uses setted resource file extension.

func GetArrayString

func GetArrayString(name string) []string

Returns the string-array resource's values with the given name. If not exists, returns nil.

func GetQuantityString

func GetQuantityString(name string, count int) string

Returns the quantity string resource's corresponding string value based on the value of the given count parameter. If the plural is not found, returns an empty string.

func GetString

func GetString(name string) string

Returns the string resource's value with the given name. If not exists, returns empty string.

func LoadValues

func LoadValues(t types.FileType) error

Loads values from strings file into internal dictionaries. Needs to be invoked only one time (but before getting strings values). Takes a FileType parameter to specify strings file format.

func NewQuantityString

func NewQuantityString(name string, values []string) (types.Plural, error)

Adds a new quantity string resource to resource file. Throws an error if the chosen name is already inserted or it is an empty string. The function uses only the first 5 values in the array. The first values is assigned to "zero" quantity. The second values is assigned to "one" quantity. The third values is assigned to "two" quantity. The fourth values is assigned to "few" quantity. The fifth values is assigned to "more" quantity.

func NewString

func NewString(name, value string) (types.String, error)

Adds a new string resource to resource file. Throws an error if the chosen name is already inserted or it is an empty string.

func NewStringArray

func NewStringArray(name string, values []string) (types.StringArray, error)

Adds a new string-array resource to resource file. Throws an error if the chosen name is already inserted or it is an empty string.

func SetFewThreshold

func SetFewThreshold(value int)

Sets the threshold for "few" values in quantity strings. When getting quantity strings values, the function checks if the given count is less OR EQUAL to this value. (default value: 20)

func SetResourceType

func SetResourceType(t types.FileType)