getting_started

Documentation

Overview

Package getting_started provides testable examples for Section "Getting Started" in the Readme.

Example (CreateAnEnvironmentWithASubmodel)

package main

import (
	"fmt"
	aastypes "github.com/aas-core-works/aas-core3.0-golang/types"
)

func main() {
	// Create a new instance of the `value` and return the pointer to it.
	NewString := func(value string) *string {
		return &value
	}

	// Create the first element
	someElement := aastypes.NewProperty(
		aastypes.DataTypeDefXSDString,
	)
	someElement.SetIDShort(
		NewString("someProperty"),
	)
	someElement.SetValue(
		NewString("some-value"),
	)

	// Create the second element
	anotherElement := aastypes.NewBlob(
		"application/octet-stream",
	)
	anotherElement.SetIDShort(
		NewString("someBlob"),
	)
	anotherElement.SetValue(
		[]byte{0xDE, 0xAD, 0xBE, 0xEF},
	)

	// Nest the elements in a submodel
	submodel := aastypes.NewSubmodel(
		"some-unique-global-identifier",
	)
	submodel.SetSubmodelElements(
		[]aastypes.ISubmodelElement{
			someElement,
			anotherElement,
		},
	)

	// Now create the environment to wrap it all up
	environment := aastypes.NewEnvironment()
	environment.SetSubmodels(
		[]aastypes.ISubmodel{
			submodel,
		},
	)

	// You can set the properties.
	environment.Submodels()[0].SubmodelElements()[0].(aastypes.IProperty).SetValue(
		NewString("changed-value"),
	)

	// You can access the properties from the children.
	fmt.Printf(
		"%v\n",
		*environment.Submodels()[0].SubmodelElements()[0].(aastypes.IProperty).Value(),
	)
}

Output:

changed-value

Example (EnhancingParentChild)

package main

import (
	"fmt"
	aasenhancing "github.com/aas-core-works/aas-core3.0-golang/enhancing"
	aastypes "github.com/aas-core-works/aas-core3.0-golang/types"
)

type ParentEnhancement struct {
	Parent aastypes.IClass
}

type stack []aastypes.IClass

func (s *stack) Push(v aastypes.IClass) {
	*s = append(*s, v)
}

func (s *stack) Pop() aastypes.IClass {
	result := (*s)[len(*s)-1]
	*s = (*s)[:len(*s)-1]
	return result
}

func main() {
	// Create a new instance of the `value` and return the pointer to it.
	NewString := func(value string) *string {
		return &value
	}

	// Prepare the environment
	someElement := aastypes.NewProperty(
		aastypes.DataTypeDefXSDString,
	)
	someElement.SetIDShort(
		NewString("someProperty"),
	)
	someElement.SetValue(
		NewString("some-value"),
	)

	submodel := aastypes.NewSubmodel(
		"some-unique-global-identifier",
	)
	submodel.SetSubmodelElements(
		[]aastypes.ISubmodelElement{
			someElement,
		},
	)

	var environment aastypes.IEnvironment
	environment = aastypes.NewEnvironment()
	environment.SetSubmodels(
		[]aastypes.ISubmodel{
			submodel,
		},
	)

	// Wrap everything
	factory := func(that aastypes.IClass) (enh *ParentEnhancement, shouldEnh bool) {
		enh = &ParentEnhancement{}
		shouldEnh = true
		return
	}

	environment = aasenhancing.Wrap[*ParentEnhancement](
		environment,
		factory,
	).(aastypes.IEnvironment)

	// Initialize the parents
	var s stack
	s.Push(environment)
	for len(s) > 0 {
		instance := s.Pop()
		instance.DescendOnce(
			func(child aastypes.IClass) (abort bool) {
				enh := aasenhancing.MustUnwrap[*ParentEnhancement](child)
				enh.Parent = instance

				s.Push(child)
				return
			},
		)
	}

	// Retrieve the parent of the first submodel
	parent := aasenhancing.MustUnwrap[*ParentEnhancement](
		environment.Submodels()[0],
	).Parent

	fmt.Printf("%v\n", parent == environment)
}

Output:

true

Example (EnhancingReferable)

package main

import (
	"fmt"
	aasenhancing "github.com/aas-core-works/aas-core3.0-golang/enhancing"
	aasstringification "github.com/aas-core-works/aas-core3.0-golang/stringification"
	aastypes "github.com/aas-core-works/aas-core3.0-golang/types"
)

type ReferableEnhancement struct {
	ID int
}

func main() {
	// Create a new instance of the `value` and return the pointer to it.
	NewString := func(value string) *string {
		return &value
	}

	// Prepare the environment
	someElement := aastypes.NewProperty(
		aastypes.DataTypeDefXSDString,
	)
	someElement.SetIDShort(
		NewString("someProperty"),
	)
	someElement.SetValue(
		NewString("some-value"),
	)

	administrativeInfo := aastypes.NewAdministrativeInformation()
	administrativeInfo.SetVersion(
		NewString("1.0"),
	)

	submodel := aastypes.NewSubmodel(
		"some-unique-global-identifier",
	)
	submodel.SetSubmodelElements(
		[]aastypes.ISubmodelElement{
			someElement,
		},
	)
	submodel.SetAdministration(administrativeInfo)

	var environment aastypes.IEnvironment
	environment = aastypes.NewEnvironment()
	environment.SetSubmodels(
		[]aastypes.ISubmodel{
			submodel,
		},
	)

	// Wrap everything
	nextID := 0

	factory := func(that aastypes.IClass) (enh *ReferableEnhancement, shouldEnh bool) {
		if aastypes.IsReferable(that) {
			enh = &ReferableEnhancement{ID: nextID}
			shouldEnh = true

			nextID++
		}

		return
	}

	environment = aasenhancing.Wrap[*ReferableEnhancement](
		environment,
		factory,
	).(aastypes.IEnvironment)

	environment.Descend(
		func(that aastypes.IClass) (abort bool) {
			enh, ok := aasenhancing.Unwrap[*ReferableEnhancement](that)
			if ok {
				fmt.Printf(
					"%s ID: %d\n",
					aasstringification.MustModelTypeToString(that.ModelType()),
					enh.ID,
				)
			} else {
				fmt.Printf(
					"%s No ID\n",
					aasstringification.MustModelTypeToString(that.ModelType()),
				)
			}
			return
		},
	)
}

Output:

Submodel ID: 0
AdministrativeInformation No ID
Property ID: 1

Example (IsXxx)

package main

import (
	"fmt"
	aastypes "github.com/aas-core-works/aas-core3.0-golang/types"
)

func main() {
	// Create the first element
	someElement := aastypes.NewProperty(
		aastypes.DataTypeDefXSDInt,
	)

	fmt.Printf("%v\n", aastypes.IsSubmodelElement(someElement))
	fmt.Printf("%v\n", aastypes.IsProperty(someElement))
	fmt.Printf("%v\n", aastypes.IsBlob(someElement))
}

Output:

true
true
false

Example (IterateOverEnumerationLiterals)

package main

import (
	"fmt"
	aasstringification "github.com/aas-core-works/aas-core3.0-golang/stringification"

	aastypes "github.com/aas-core-works/aas-core3.0-golang/types"
)

func main() {
	for _, literal := range aastypes.LiteralsOfModellingKind {
		fmt.Printf(
			"Literal as number: %d, literal as string: %s\n",
			literal, aasstringification.MustModellingKindToString(literal),
		)
	}
}

Output:

Literal as number: 0, literal as string: Template
Literal as number: 1, literal as string: Instance

Example (IterateOverEnvironment)

package main

import (
	"fmt"
	aastypes "github.com/aas-core-works/aas-core3.0-golang/types"
	"strings"
)

func main() {
	// Create a new instance of the `value` and return the pointer to it.
	NewString := func(value string) *string {
		return &value
	}

	// Prepare the environment
	someElement := aastypes.NewProperty(
		aastypes.DataTypeDefXSDString,
	)
	someElement.SetIDShort(
		NewString("someProperty"),
	)

	anotherElement := aastypes.NewProperty(
		aastypes.DataTypeDefXSDString,
	)
	anotherElement.SetIDShort(
		NewString("anotherProperty"),
	)

	yetAnotherElement := aastypes.NewProperty(
		aastypes.DataTypeDefXSDString,
	)
	yetAnotherElement.SetIDShort(
		NewString("yetAnotherProperty"),
	)

	submodel := aastypes.NewSubmodel(
		"some-unique-global-identifier",
	)
	submodel.SetSubmodelElements(
		[]aastypes.ISubmodelElement{
			someElement,
			anotherElement,
			yetAnotherElement,
		},
	)

	environment := aastypes.NewEnvironment()
	environment.SetSubmodels(
		[]aastypes.ISubmodel{
			submodel,
		},
	)

	// Iterate using ``Descend``
	environment.Descend(
		func(that aastypes.IClass) (abort bool) {
			if aastypes.IsProperty(that) {
				idShort := that.(aastypes.IProperty).IDShort()
				if idShort != nil &&
					strings.Contains(strings.ToLower(*idShort), "another") {
					fmt.Printf("%s\n", *idShort)
				}
			}
			return
		},
	)
}

Output:

anotherProperty
yetAnotherProperty

Example (JsonizationFrom)

package main

import (
	"encoding/json"
	"fmt"

	aasjsonization "github.com/aas-core-works/aas-core3.0-golang/jsonization"

	aasstringification "github.com/aas-core-works/aas-core3.0-golang/stringification"

	aastypes "github.com/aas-core-works/aas-core3.0-golang/types"
)

func main() {
	text := `
{
  "submodels": [
    {
      "id": "some-unique-global-identifier",
      "modelType": "Submodel",
      "submodelElements": [
        {
          "idShort": "someProperty",
          "modelType": "Property",
          "value": "some-value",
          "valueType": "xs:string"
        }
      ]
    }
  ]
}`

	bb := []byte(text)

	var jsonable map[string]interface{}
	var err error
	err = json.Unmarshal(bb, &jsonable)
	if err != nil {
		panic(err.Error())
	}

	var environment aastypes.IEnvironment
	var deseriaErr *aasjsonization.DeserializationError
	environment, deseriaErr = aasjsonization.EnvironmentFromJsonable(
		jsonable,
	)
	if deseriaErr != nil {
		panic(deseriaErr.Error())
	}

	environment.Descend(
		func(that aastypes.IClass) (abort bool) {
			fmt.Printf(
				"%s\n",
				aasstringification.MustModelTypeToString(that.ModelType()),
			)
			return
		},
	)

}

Output:

Submodel
Property

Example (JsonizationTo)

package main

import (
	"encoding/json"
	"fmt"

	aasjsonization "github.com/aas-core-works/aas-core3.0-golang/jsonization"

	aastypes "github.com/aas-core-works/aas-core3.0-golang/types"
)

func main() {
	// Create a new instance of the `value` and return the pointer to it.
	NewString := func(value string) *string {
		return &value
	}

	// Prepare the environment
	someElement := aastypes.NewProperty(
		aastypes.DataTypeDefXSDString,
	)
	someElement.SetIDShort(
		NewString("someProperty"),
	)
	someElement.SetValue(
		NewString("some-value"),
	)

	submodel := aastypes.NewSubmodel(
		"some-unique-global-identifier",
	)
	submodel.SetSubmodelElements(
		[]aastypes.ISubmodelElement{
			someElement,
		},
	)

	environment := aastypes.NewEnvironment()
	environment.SetSubmodels(
		[]aastypes.ISubmodel{
			submodel,
		},
	)

	// Serialize to jsonable
	var jsonable map[string]interface{}
	var seriaErr *aasjsonization.SerializationError
	jsonable, seriaErr = aasjsonization.ToJsonable(environment)
	if seriaErr != nil {
		panic(seriaErr.Error())
	}

	// Serialize jsonable to string
	var bb []byte
	var err error
	bb, err = json.MarshalIndent(jsonable, "", "  ")
	if err != nil {
		panic(err.Error())
	}
	text := string(bb)

	fmt.Println(text)
}

Output:

{
  "submodels": [
    {
      "id": "some-unique-global-identifier",
      "modelType": "Submodel",
      "submodelElements": [
        {
          "idShort": "someProperty",
          "modelType": "Property",
          "value": "some-value",
          "valueType": "xs:string"
        }
      ]
    }
  ]
}

Example (Verification)

package main

import (
	"fmt"
	aastypes "github.com/aas-core-works/aas-core3.0-golang/types"

	aasverification "github.com/aas-core-works/aas-core3.0-golang/verification"
)

func main() {
	// Create a new instance of the `value` and return the pointer to it.
	NewString := func(value string) *string {
		return &value
	}

	// Prepare the environment
	someElement := aastypes.NewProperty(
		aastypes.DataTypeDefXSDString,
	)
	// The ID-shorts must be proper variable names,
	// but there is a dash (`-`) in this ID-short.
	someElement.SetIDShort(
		NewString("some-property"),
	)

	submodel := aastypes.NewSubmodel(
		"some-unique-global-identifier",
	)
	submodel.SetSubmodelElements(
		[]aastypes.ISubmodelElement{
			someElement,
		},
	)

	environment := aastypes.NewEnvironment()
	environment.SetSubmodels(
		[]aastypes.ISubmodel{
			submodel,
		},
	)

	// Verify
	aasverification.Verify(
		environment,
		func(err *aasverification.VerificationError) (abort bool) {
			fmt.Printf("%s\n", err.Error())
			return
		},
	)
}

Output:

Submodels[0].SubmodelElements[0].IDShort: ID-short of Referables shall only feature letters, digits, underscore (``_``); starting mandatory with a letter. *I.e.* ``[a-zA-Z][a-zA-Z0-9_]*``.

Example (XmlizationFrom)

package main

import (
	"encoding/xml"
	"fmt"

	aasstringification "github.com/aas-core-works/aas-core3.0-golang/stringification"

	aastypes "github.com/aas-core-works/aas-core3.0-golang/types"

	aasxmlization "github.com/aas-core-works/aas-core3.0-golang/xmlization"
	"strings"
)

func main() {
	text := `<environment xmlns="https://admin-shell.io/aas/3/0">
  <submodels>
    <submodel>
      <id>some-unique-global-identifier</id>
      <submodelElements>
        <property>
          <idShort>someProperty</idShort>
          <valueType>xs:string</valueType>
          <value>some-value</value>
        </property>
      </submodelElements>
    </submodel>
  </submodels>
</environment>`

	reader := strings.NewReader(text)
	decoder := xml.NewDecoder(reader)

	var instance aastypes.IClass
	var err error
	instance, err = aasxmlization.Unmarshal(
		decoder,
	)
	if err != nil {
		panic(err.Error())
	}

	instance.Descend(
		func(that aastypes.IClass) (abort bool) {
			fmt.Printf(
				"%s\n",
				aasstringification.MustModelTypeToString(that.ModelType()),
			)
			return
		},
	)

}

Output:

Submodel
Property

Example (XmlizationTo)

package main

import (
	"encoding/xml"
	"fmt"

	aastypes "github.com/aas-core-works/aas-core3.0-golang/types"

	aasxmlization "github.com/aas-core-works/aas-core3.0-golang/xmlization"
	"strings"
)

func main() {
	// Create a new instance of the `value` and return the pointer to it.
	NewString := func(value string) *string {
		return &value
	}

	// Prepare the environment
	someElement := aastypes.NewProperty(
		aastypes.DataTypeDefXSDString,
	)
	someElement.SetIDShort(
		NewString("someProperty"),
	)
	someElement.SetValue(
		NewString("some-value"),
	)

	submodel := aastypes.NewSubmodel(
		"some-unique-global-identifier",
	)
	submodel.SetSubmodelElements(
		[]aastypes.ISubmodelElement{
			someElement,
		},
	)

	environment := aastypes.NewEnvironment()
	environment.SetSubmodels(
		[]aastypes.ISubmodel{
			submodel,
		},
	)

	// Serialize to XML
	builder := new(strings.Builder)
	encoder := xml.NewEncoder(builder)
	encoder.Indent("", "  ")

	// We want to include the namespace in the root XML element.
	withNamespace := true

	var err error
	err = aasxmlization.Marshal(encoder, environment, withNamespace)
	if err != nil {
		panic(err.Error())
	}

	text := builder.String()

	fmt.Println(text)
}

Output:

<environment xmlns="https://admin-shell.io/aas/3/0">
  <submodels>
    <submodel>
      <id>some-unique-global-identifier</id>
      <submodelElements>
        <property>
          <idShort>someProperty</idShort>
          <valueType>xs:string</valueType>
          <value>some-value</value>
        </property>
      </submodelElements>
    </submodel>
  </submodels>
</environment>