properties

package module
v1.8.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 5, 2024 License: GPL-2.0 Imports: 13 Imported by: 37

README

GoDoc Check License status Check Markdown status Check Taskfiles status

Package properties is a library for handling maps of hierarchical properties.

This library is mainly used in the Arduino platform software to handle configurations made of key/value pairs stored in files with an INI like syntax.

This map also keeps the insertion order when ranging through the Keys() method.

For more information read the docs here.

Security

If you think you found a vulnerability or other security-related bug in this project, please read our security policy and report the bug to our Security Team 🛡️ Thank you!

e-mail contact: security@arduino.cc

Documentation

Overview

Package properties is a library for handling maps of hierarchical properties. This library is mainly used in the Arduino platform software to handle configurations made of key/value pairs stored in files with an INI like syntax, for example: 

...
uno.name=Arduino/Genuino Uno
uno.upload.tool=avrdude
uno.upload.protocol=arduino
uno.upload.maximum_size=32256
uno.upload.maximum_data_size=2048
uno.upload.speed=115200
uno.build.mcu=atmega328p
uno.build.f_cpu=16000000L
uno.build.board=AVR_UNO
uno.build.core=arduino
uno.build.variant=standard
diecimila.name=Arduino Duemilanove or Diecimila
diecimila.upload.tool=avrdude
diecimila.upload.protocol=arduino
diecimila.build.f_cpu=16000000L
diecimila.build.board=AVR_DUEMILANOVE
diecimila.build.core=arduino
diecimila.build.variant=standard
...

This library has methods to parse this kind of file into a Map object.

The Map internally keeps the insertion order so it can be retrieved later when cycling through the key sets.

The Map object has many helper methods to accomplish some common operations on this kind of data like cloning, merging, comparing and also extracting a submap or generating a map-of-submaps from the first "level" of the hierarchy.

On the Arduino platform the properties are used to populate command line recipes so there are some methods to help this task like SplitQuotedString or ExpandPropsInString.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func DeleteUnexpandedPropsFromString 

func DeleteUnexpandedPropsFromString(str string) string

DeleteUnexpandedPropsFromString removes all the brace markers "{xxx}" that are not expanded into a value using the Map.ExpandPropsInString() method.

func GetOSSuffix 

func GetOSSuffix() string

GetOSSuffix returns the os name used to filter os-specific properties in Load* functions

func MergeMapsOfProperties 

func MergeMapsOfProperties(target map[string]*Map, sources ...map[string]*Map) map[string]*Map

MergeMapsOfProperties merges the map-of-Maps (obtained from the method FirstLevelOf()) into the target map-of-Maps.

func SetOSSuffix added in v1.7.0 

func SetOSSuffix(suffix string)

SetOSSuffix forces the OS suffix to the given value

func SplitQuotedString 

func SplitQuotedString(src string, quoteChars string, acceptEmptyArguments bool) ([]string, error)

SplitQuotedString splits a string by spaces and at the same time allows to use spaces in a single element of the split using quote characters.

For example the call: 

SplitQuotedString(`This 'is an' "Hello World!" example`, `'"`, false)

returns the following array: 

[]string{"This", "is an", "Hello World!", "example"}

The quoteChars parameter is a string containing all the characters that are considered as quote characters. If a quote character is found, the function will consider the text between the quote character and the next quote character as a single element of the split.

The acceptEmptyArguments parameter is a boolean that indicates if the function should consider empty arguments as valid elements of the split. If set to false, the function will ignore empty arguments.

If the function finds an opening quote character and does not find the closing quote character, it will return an error. In any case, the function will return the split array up to the point where the error occurred.

The function does not support escaping of quote characters.

The function is UTF-8 safe.

Types

type Map 

type Map struct {

	// Debug if set to true ExpandPropsInString will always output debugging information
	Debug bool
	// contains filtered or unexported fields
}

Map is a container of properties

func Load 

func Load(filepath string) (*Map, error)

Load reads a properties file and makes a Map out of it.

func LoadFromBytes added in v1.3.0 

func LoadFromBytes(bytes []byte) (*Map, error)

LoadFromBytes reads properties data and makes a Map out of it.

func LoadFromPath 

func LoadFromPath(path *paths.Path) (*Map, error)

LoadFromPath reads a properties file and makes a Map out of it.

func LoadFromSlice 

func LoadFromSlice(lines []string) (*Map, error)

LoadFromSlice reads a properties file from an array of string and makes a Map out of it

func NewFromHashmap 

func NewFromHashmap(orig map[string]string) *Map

NewFromHashmap creates a new Map from the given map[string]string. Insertion order is not preserved.

func NewMap 

func NewMap() *Map

NewMap returns a new Map

func SafeLoad 

func SafeLoad(filepath string) (*Map, error)

SafeLoad is like Load, except that it returns an empty Map if the specified file doesn't exist

func SafeLoadFromPath 

func SafeLoadFromPath(path *paths.Path) (*Map, error)

SafeLoadFromPath is like LoadFromPath, except that it returns an empty Map if the specified file doesn't exist

func (*Map) AsMap 

func (m *Map) AsMap() map[string]string

AsMap returns the underlying map[string]string. This is useful if you need to for ... range but without the requirement of the ordered elements.

func (*Map) AsSlice added in v1.7.2 

func (m *Map) AsSlice() []string

AsSlice returns the underlying map[string]string as a slice of strings with the pattern `{key}={value}`, maintaining the insertion order of the keys.

func (*Map) Clone 

func (m *Map) Clone() *Map

Clone makes a copy of the Map

func (*Map) ContainsKey 

func (m *Map) ContainsKey(key string) bool

ContainsKey returns true if the map contains the specified key

func (*Map) ContainsValue added in v1.2.0 

func (m *Map) ContainsValue(value string) bool

ContainsValue returns true if the map contains the specified value

func (*Map) DebugExpandPropsInString added in v1.1.0 

func (m *Map) DebugExpandPropsInString(str string) string

DebugExpandPropsInString outputs the substitutions made by ExpandPropsInString for debugging purposes.

func (*Map) Dump 

func (m *Map) Dump() string

Dump returns a representation of the map in golang source format

func (*Map) Equals 

func (m *Map) Equals(other *Map) bool

Equals returns true if the current Map contains the same key/value pairs of the Map passed as argument, the order of insertion does not matter.

func (*Map) EqualsWithOrder 

func (m *Map) EqualsWithOrder(other *Map) bool

EqualsWithOrder returns true if the current Map contains the same key/value pairs of the Map passed as argument with the same order of insertion.

func (*Map) ExpandPropsInString 

func (m *Map) ExpandPropsInString(str string) string

ExpandPropsInString uses the Map to replace values into a format string. The format string should contains markers between braces, for example: 

"The selected upload protocol is {upload.protocol}."

Each marker is replaced by the corresponding value of the Map. The values in the Map may contain other markers, they are evaluated recursively up to 10 times.

func (*Map) ExtractSubIndexLists added in v1.5.0 

func (m *Map) ExtractSubIndexLists(root string) []string

ExtractSubIndexLists extracts a list of arguments from a root `root.N=...`. For example the following Map: 

properties.Map{
  "uno.discovery.required": "item",
  "due.discovery.required.0": "item1",
  "due.discovery.required.1": "item2",
  "due.discovery.required.2": "item3",
  "tre.discovery.required.1": "itemA",
  "tre.discovery.required.2": "itemB",
  "tre.discovery.required.3": "itemC",
  "quattro.discovery.required.1": "itemA",
  "quattro.discovery.required.4": "itemB",
  "quattro.discovery.required.5": "itemC",
}

calling ExtractSubIndexLists("uno.discovery.required") returns the array: 

[ "item" ]

calling ExtractSubIndexLists("due.discovery.required") returns the array: 

[ "item1", "item2", "item3" ]

the sub-index may start with .1 too, so calling ExtractSubIndexLists("tre.discovery.required") returns: 

[ "itemA", "itemB", "itemC" ]

also the list may contains holes, so calling ExtractSubIndexLists("quattro.discovery.required") returns: 

[ "itemA", "itemB", "itemC" ]

Numeric subindex cannot be mixed with non-numeric, in that case only the numeric sub index sets will be returned.

func (*Map) ExtractSubIndexSets added in v1.5.0 

func (m *Map) ExtractSubIndexSets(root string) []*Map

ExtractSubIndexSets works like SubTree but it considers also the numeric sub index in the form `root.N.xxx...` as separate subsets. For example the following Map: 

properties.Map{
  "uno.upload_port.vid": "0x1000",
  "uno.upload_port.pid": "0x2000",
  "due.upload_port.0.vid": "0x1000",
  "due.upload_port.0.pid": "0x2000",
  "due.upload_port.1.vid": "0x1001",
  "due.upload_port.1.pid": "0x2001",
  "tre.upload_port.1.vid": "0x1001",
  "tre.upload_port.1.pid": "0x2001",
  "tre.upload_port.2.vid": "0x1002",
  "tre.upload_port.2.pid": "0x2002",
}

calling ExtractSubIndexSets("uno.upload_port") returns the array: 

[ properties.Map{
    "vid": "0x1000",
    "pid": "0x2000",
  },
]

calling ExtractSubIndexSets("due.upload_port") returns the array: 

[ properties.Map{
    "vid": "0x1000",
    "pid": "0x2000",
  },
  properties.Map{
    "vid": "0x1001",
    "pid": "0x2001",
  },
]

the sub-index may start with .1 too, so calling ExtractSubIndexSets("tre.upload_port") returns: 

[ properties.Map{
    "vid": "0x1001",
    "pid": "0x2001",
  },
  properties.Map{
    "vid": "0x1002",
    "pid": "0x2002",
  },
]

Numeric subindex cannot be mixed with non-numeric, in that case only the numeric sub index sets will be returned.

func (*Map) FirstLevelKeys 

func (m *Map) FirstLevelKeys() []string

FirstLevelKeys returns the keys in the first level of the hierarchy of the current Map. For example the following Map: 

properties.Map{
  "uno.name": "Arduino/Genuino Uno",
  "uno.upload.tool": "avrdude",
  "uno.upload.protocol": "arduino",
  "uno.upload.maximum_size": "32256",
  "diecimila.name": "Arduino Duemilanove or Diecimila",
  "diecimila.upload.tool": "avrdude",
  "diecimila.upload.protocol": "arduino",
  "diecimila.bootloader.tool": "avrdude",
  "diecimila.bootloader.low_fuses": "0xFF",
}

will produce the following result: 

[]string{
  "uno",
  "diecimila",
}

the order of the original map is preserved

func (*Map) FirstLevelOf 

func (m *Map) FirstLevelOf() map[string]*Map

FirstLevelOf generates a map-of-Maps using the first level of the hierarchy of the current Map. For example the following Map: 

properties.Map{
  "uno.name": "Arduino/Genuino Uno",
  "uno.upload.tool": "avrdude",
  "uno.upload.protocol": "arduino",
  "uno.upload.maximum_size": "32256",
  "diecimila.name": "Arduino Duemilanove or Diecimila",
  "diecimila.upload.tool": "avrdude",
  "diecimila.upload.protocol": "arduino",
  "diecimila.bootloader.tool": "avrdude",
  "diecimila.bootloader.low_fuses": "0xFF",
}

is transformed into the following map-of-Maps: 

map[string]Map{
  "uno" : properties.Map{
    "name": "Arduino/Genuino Uno",
    "upload.tool": "avrdude",
    "upload.protocol": "arduino",
    "upload.maximum_size": "32256",
  },
  "diecimila" : properties.Map{
    "name": "Arduino Duemilanove or Diecimila",
    "upload.tool": "avrdude",
    "upload.protocol": "arduino",
    "bootloader.tool": "avrdude",
    "bootloader.low_fuses": "0xFF",
  }
}

func (*Map) Get 

func (m *Map) Get(key string) string

Get retrieves the value corresponding to key

func (*Map) GetBoolean 

func (m *Map) GetBoolean(key string) bool

GetBoolean returns true if the map contains the specified key and the value equals to the string "true", in any other case returns false.

func (*Map) GetOk 

func (m *Map) GetOk(key string) (string, bool)

GetOk retrieves the value corresponding to key and returns a true/false indicator to check if the key is present in the map (true if the key is present)

func (*Map) GetPath 

func (m *Map) GetPath(key string) *paths.Path

GetPath returns a paths.Path object using the map value as path. The function returns nil if the key is not present.

func (*Map) IsPropertyMissingInExpandPropsInString added in v1.3.0 

func (m *Map) IsPropertyMissingInExpandPropsInString(prop, str string) bool

IsPropertyMissingInExpandPropsInString checks if a property 'prop' is missing when the ExpandPropsInString method is applied to the input string 'str'. This method returns false if the 'prop' is defined in the map or if 'prop' is not used in the string expansion of 'str', otherwise the method returns true.

func (*Map) Keys 

func (m *Map) Keys() []string

Keys returns an array of the keys contained in the Map

func (*Map) MarshalJSON 

func (m *Map) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler interface

func (*Map) Merge 

func (m *Map) Merge(sources ...*Map) *Map

Merge merges other Maps into this one. Each key/value of the merged Maps replaces the key/value present in the original Map.

func (*Map) Remove 

func (m *Map) Remove(key string)

Remove removes the key from the map

func (*Map) Set 

func (m *Map) Set(key, value string)

Set inserts or replaces an existing key-value pair in the map

func (*Map) SetBoolean 

func (m *Map) SetBoolean(key string, value bool)

SetBoolean sets the specified key to the string "true" or "false" if the value is respectively true or false.

func (*Map) SetPath 

func (m *Map) SetPath(key string, value *paths.Path)

SetPath saves the paths.Path object in the map using the path as value of the map

func (*Map) Size 

func (m *Map) Size() int

Size returns the number of elements in the map

func (*Map) SubTree 

func (m *Map) SubTree(rootKey string) *Map

SubTree extracts a sub Map from an existing map using the first level of the keys hierarchy as selector. For example the following Map: 

properties.Map{
  "uno.name": "Arduino/Genuino Uno",
  "uno.upload.tool": "avrdude",
  "uno.upload.protocol": "arduino",
  "uno.upload.maximum_size": "32256",
  "diecimila.name": "Arduino Duemilanove or Diecimila",
  "diecimila.upload.tool": "avrdude",
  "diecimila.upload.protocol": "arduino",
  "diecimila.bootloader.tool": "avrdude",
  "diecimila.bootloader.low_fuses": "0xFF",
}

after calling SubTree("uno") will be transformed into: 

properties.Map{
  "name": "Arduino/Genuino Uno",
  "upload.tool": "avrdude",
  "upload.protocol": "arduino",
  "upload.maximum_size": "32256",
},

func (*Map) UnmarshalJSON 

func (m *Map) UnmarshalJSON(d []byte) error

UnmarshalJSON implements json.Unmarshaler interface

func (*Map) Values 

func (m *Map) Values() []string

Values returns an array of the values contained in the Map. Duplicated values are repeated in the list accordingly.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.