properties
packagemodule
This package is not in the latest version of its module.
Details
Validgo.mod file
The Go module system was introduced in Go 1.11 and is the official dependency management solution for Go.
- Redistributable license
Redistributable licenses place minimal restrictions on how software can be used, modified, and redistributed.
- Tagged version
Modules with tagged versions give importers more predictable builds.
- Stable version
When a project reaches major version v1 it is considered stable.
- Learn more about best practices
Repository
Links
Open Source Insights
README¶
Packageproperties is a library for handling maps of hierarchical properties.
This library is mainly used in the Arduino platform software to handleconfigurations made of key/value pairs stored in files with an INI likesyntax.
This map also keeps the insertion order when ranging through theKeys() method.
For more information read the docshere.
Security
If you think you found a vulnerability or other security-related bug in this project, please read oursecurity 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 handleconfigurations made of key/value pairs stored in files with an INI likesyntax, for example:
...uno.name=Arduino/Genuino Unouno.upload.tool=avrdudeuno.upload.protocol=arduinouno.upload.maximum_size=32256uno.upload.maximum_data_size=2048uno.upload.speed=115200uno.build.mcu=atmega328puno.build.f_cpu=16000000Luno.build.board=AVR_UNOuno.build.core=arduinouno.build.variant=standarddiecimila.name=Arduino Duemilanove or Diecimiladiecimila.upload.tool=avrdudediecimila.upload.protocol=arduinodiecimila.build.f_cpu=16000000Ldiecimila.build.board=AVR_DUEMILANOVEdiecimila.build.core=arduinodiecimila.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 whencycling through the key sets.
The Map object has many helper methods to accomplish some common operationson this kind of data like cloning, merging, comparing and also extractinga 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 recipesso there are some methods to help this task like SplitQuotedString or ExpandPropsInString.
Index¶
- func DeleteUnexpandedPropsFromString(str string) string
- func GetOSSuffix() string
- func MergeMapsOfProperties(target map[string]*Map, sources ...map[string]*Map) map[string]*Map
- func SetOSSuffix(suffix string)
- func SplitQuotedString(src string, quoteChars string, acceptEmptyArguments bool) ([]string, error)
- type Map
- func Load(filepath string) (*Map, error)
- func LoadFromBytes(bytes []byte) (*Map, error)
- func LoadFromPath(path *paths.Path) (*Map, error)
- func LoadFromSlice(lines []string) (*Map, error)
- func NewFromHashmap(orig map[string]string) *Map
- func NewMap() *Map
- func SafeLoad(filepath string) (*Map, error)
- func SafeLoadFromPath(path *paths.Path) (*Map, error)
- func (m *Map) AsMap() map[string]string
- func (m *Map) AsSlice() []string
- func (m *Map) Clone() *Map
- func (m *Map) ContainsKey(key string) bool
- func (m *Map) ContainsValue(value string) bool
- func (m *Map) DebugExpandPropsInString(str string) string
- func (m *Map) Dump() string
- func (m *Map) Equals(other *Map) bool
- func (m *Map) EqualsWithOrder(other *Map) bool
- func (m *Map) ExpandPropsInString(str string) string
- func (m *Map) ExtractSubIndexLists(root string) []string
- func (m *Map) ExtractSubIndexSets(root string) []*Map
- func (m *Map) FirstLevelKeys() []string
- func (m *Map) FirstLevelOf() map[string]*Map
- func (m *Map) Get(key string) string
- func (m *Map) GetBoolean(key string) bool
- func (m *Map) GetOk(key string) (string, bool)
- func (m *Map) GetPath(key string) *paths.Path
- func (m *Map) IsPropertyMissingInExpandPropsInString(prop, str string) bool
- func (m *Map) Keys() []string
- func (m *Map) MarshalJSON() ([]byte, error)
- func (m *Map) Merge(sources ...*Map) *Map
- func (m *Map) Remove(key string)
- func (m *Map) Set(key, value string)
- func (m *Map) SetBoolean(key string, value bool)
- func (m *Map) SetPath(key string, value *paths.Path)
- func (m *Map) Size() int
- func (m *Map) SubTree(rootKey string) *Map
- func (m *Map) UnmarshalJSON(d []byte) error
- func (m *Map) Values() []string
Constants¶
This section is empty.
Variables¶
This section is empty.
Functions¶
funcDeleteUnexpandedPropsFromString¶
DeleteUnexpandedPropsFromString removes all the brace markers "{xxx}" that are not expandedinto a value using the Map.ExpandPropsInString() method.
funcGetOSSuffix¶
func GetOSSuffix()string
GetOSSuffix returns the os name used to filter os-specific properties in Load* functions
funcMergeMapsOfProperties¶
MergeMapsOfProperties merges the map-of-Maps (obtained from the method FirstLevelOf()) into thetarget map-of-Maps.
funcSetOSSuffix¶added inv1.7.0
func SetOSSuffix(suffixstring)
SetOSSuffix forces the OS suffix to the given value
funcSplitQuotedString¶
SplitQuotedString splits a string by spaces and at the same time allowsto 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 thatare considered as quote characters. If a quote character is found, thefunction will consider the text between the quote character and the nextquote character as a single element of the split.
The acceptEmptyArguments parameter is a boolean that indicates if thefunction 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 theclosing quote character, it will return an error. In any case, the functionwill 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¶
typeMap¶
type Map struct {// Debug if set to true ExpandPropsInString will always output debugging informationDebugbool// contains filtered or unexported fields}Map is a container of properties
funcLoadFromBytes¶added inv1.3.0
LoadFromBytes reads properties data and makes a Map out of it.
funcLoadFromPath¶
LoadFromPath reads a properties file and makes a Map out of it.
funcLoadFromSlice¶
LoadFromSlice reads a properties file from an array of stringand makes a Map out of it
funcNewFromHashmap¶
NewFromHashmap creates a new Map from the given map[string]string.Insertion order is not preserved.
funcSafeLoad¶
SafeLoad is like Load, except that it returns an empty Map if the specifiedfile doesn't exist
funcSafeLoadFromPath¶
SafeLoadFromPath is like LoadFromPath, except that it returns an empty Map ifthe specified file doesn't exist
func (*Map)AsMap¶
AsMap returns the underlying map[string]string. This is useful if you need tofor ... range but without the requirement of the ordered elements.
func (*Map)AsSlice¶added inv1.7.2
AsSlice returns the underlying map[string]string as a slice ofstrings with the pattern `{key}={value}`, maintaining the insertion order of the keys.
func (*Map)ContainsKey¶
ContainsKey returns true if the map contains the specified key
func (*Map)ContainsValue¶added inv1.2.0
ContainsValue returns true if the map contains the specified value
func (*Map)DebugExpandPropsInString¶added inv1.1.0
DebugExpandPropsInString outputs the substitutions made byExpandPropsInString for debugging purposes.
func (*Map)Equals¶
Equals returns true if the current Map contains the same key/value pairs ofthe Map passed as argument, the order of insertion does not matter.
func (*Map)EqualsWithOrder¶
EqualsWithOrder returns true if the current Map contains the same key/value pairs ofthe Map passed as argument with the same order of insertion.
func (*Map)ExpandPropsInString¶
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 evaluatedrecursively up to 10 times.
func (*Map)ExtractSubIndexLists¶added inv1.5.0
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 subindex sets will be returned.
func (*Map)ExtractSubIndexSets¶added inv1.5.0
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 subindex sets will be returned.
func (*Map)FirstLevelKeys¶
FirstLevelKeys returns the keys in the first level of the hierarchyof 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¶
FirstLevelOf generates a map-of-Maps using the first level of the hierarchyof 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)GetBoolean¶
GetBoolean returns true if the map contains the specified key and the valueequals to the string "true", in any other case returns false.
func (*Map)GetOk¶
GetOk retrieves the value corresponding to key and returns a true/false indicatorto check if the key is present in the map (true if the key is present)
func (*Map)GetPath¶
GetPath returns a paths.Path object using the map value as path. The functionreturns nil if the key is not present.
func (*Map)IsPropertyMissingInExpandPropsInString¶added inv1.3.0
IsPropertyMissingInExpandPropsInString checks if a property 'prop' is missingwhen the ExpandPropsInString method is applied to the input string 'str'.This method returns false if the 'prop' is defined in the mapor if 'prop' is not used in the string expansion of 'str', otherwisethe method returns true.
func (*Map)MarshalJSON¶
MarshalJSON implements json.Marshaler interface
func (*Map)Merge¶
Merge merges other Maps into this one. Each key/value of the merged Maps replacesthe key/value present in the original Map.
func (*Map)SetBoolean¶
SetBoolean sets the specified key to the string "true" or "false" if the valueis respectively true or false.
func (*Map)SetPath¶
SetPath saves the paths.Path object in the map using the path as value of the map
func (*Map)SubTree¶
SubTree extracts a sub Map from an existing map using the first levelof 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¶
UnmarshalJSON implements json.Unmarshaler interface
Source Files