README
¶
go-whosonfirst-export
Go package for exporting Who's On First documents.
Documentation
Motivation
This package is designed to perform all the steps necessary to "export" (as in create or update) a Who's On First record taking care to ensure correct formatting, default values and validation.
Example
Version 3.x of this package introduce major, backward-incompatible changes from earlier releases. That said, migragting from version 2.x to 3.x should be relatively straightforward as the basic concepts are still the same but (hopefully) simplified. There are some important changes "under the hood" but the user-facing changes, while important, should be easy to update.
All error handling removed for the sake of brevity.
Simple
import (
"context"
"os
"github.com/whosonfirst/go-whosonfirst-export/v3"
)
func main() {
ctx := context.Background()
body, _ := os.ReadFile(path)
has_changed, new_body, _ := export.Export(ctx, body)
if has_changes {
os.Stdout.Write(new_body)
}
}
This is how you would have done the same thing using the /v2 release:
import (
"context"
"os
"github.com/whosonfirst/go-whosonfirst-export/v2"
)
func main() {
ctx := context.Background()
body, _ := os.ReadFile(path)
opts, _ := export.NewDefaultOptions(ctx)
export.Export(body, opts, os.Stdout)
}
Exporter
The Exporter interface provides a common interface to allow for customized export functionality in your code which can supplement the default export functionality with application-specific needs. The interface consists of a single method whose signature matches the standard Export method:
type Exporter interface {
Export(context.Context, []byte) (bool, []byte, error)
}
Custom Exporter implementations are "registered" at runtime with the export.RegisterExporter method. For example:
type CustomExporter struct {
export.Exporter
}
func init() {
ctx := context.Background()
export.RegisterExporter(ctx, "custom", NewCustomExporter)
}
func NewWhosOnFirstExporter(ctx context.Context, uri string) (export.Exporter, error) {
// Your code here...
}
For a complete implementation consult exporter_whosonfirst.go.
whosonfirst://
This package provides a default whosonfirst:// exporter implementation (which is really just a thin wrapper around the Export method) which can be used like this:
import (
"context"
"os
"github.com/whosonfirst/go-whosonfirst-export/v3"
)
func main() {
ctx := context.Background()
ex, _ := export.NewExporter(ctx, "whosonfirst://")
path := "some.geojson"
body, _ := os.ReadFile(path)
has_changes, body, _ = ex.Export(ctx, body)
if has_changes {
os.Stdout.Write(body)
}
}
This is how you would have done the same thing using the /v2 release:
import (
"context"
"os
"github.com/whosonfirst/go-whosonfirst-export/v2"
)
func main() {
ctx := context.Background()
ex, _ := export.NewExporter(ctx, "whosonfirst://")
path := "some.geojson"
body, _ := os.ReadFile(path)
body, _ = ex.Export(ctx, body)
os.Stdout.Write(body)
}
See also
Documentation
¶
Overview ¶
go-whosonfirst-export is a Go package for exporting Who's On First documents in Go.
Example
import (
"context"
"os
"github.com/whosonfirst/go-whosonfirst-export/v3"
)
func main() {
ctx := context.Background()
ex, _ := export.NewExporter(ctx, "whosonfirst://")
path := "some.geojson"
body, _ := os.ReadFile(path)
has_changed, body, _ = ex.Export(ctx, body)
if has_changed {
os.Stdout.Write(body)
}
}
Index ¶
- func AssignProperties(ctx context.Context, body []byte, to_assign map[string]interface{}) ([]byte, error)
- func AssignPropertiesIfChanged(ctx context.Context, body []byte, to_assign map[string]interface{}) (bool, []byte, error)
- func CessateRecord(ctx context.Context, ex Exporter, old_body []byte) ([]byte, error)
- func CessateRecordWithTime(ctx context.Context, ex Exporter, t time.Time, old_body []byte) ([]byte, error)
- func DeprecateRecord(ctx context.Context, ex Exporter, old_body []byte) ([]byte, error)
- func DeprecateRecordWithTime(ctx context.Context, ex Exporter, t time.Time, old_body []byte) ([]byte, error)
- func EnsureProperties(ctx context.Context, body []byte, to_ensure map[string]interface{}) ([]byte, error)
- func Export(ctx context.Context, feature []byte) (bool, []byte, error)
- func ExporterSchemes() []string
- func HasChanges(ctx context.Context, old_feature []byte, new_feature []byte) (bool, error)
- func PrepareAltFeatureWithoutTimestamps(ctx context.Context, feature []byte) ([]byte, error)
- func PrepareFeatureWithoutTimestamps(ctx context.Context, feature []byte) ([]byte, error)
- func PrepareTimestamps(ctx context.Context, feature []byte) ([]byte, error)
- func RegisterExporter(ctx context.Context, scheme string, init_func ExporterInitializationFunc) error
- func RemoveProperties(ctx context.Context, body []byte, to_remove []string) ([]byte, error)
- func RemovePropertiesIfChanged(ctx context.Context, body []byte, to_remove []string) (bool, []byte, error)
- func SupersedeRecord(ctx context.Context, ex Exporter, old_body []byte) ([]byte, []byte, error)
- func SupersedeRecordWithParent(ctx context.Context, ex Exporter, to_supersede_f []byte, parent_f []byte) ([]byte, []byte, error)
- func WriteExportIfChanged(ctx context.Context, feature []byte, wr io.Writer) (bool, error)
- type Exporter
- type ExporterInitializationFunc
- type WhosOnFirstExporter
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func AssignProperties ¶
func AssignProperties(ctx context.Context, body []byte, to_assign map[string]interface{}) ([]byte, error)
EnsureProperties writes all the properties in 'to_assign' to 'body'.
func AssignPropertiesIfChanged ¶
func AssignPropertiesIfChanged(ctx context.Context, body []byte, to_assign map[string]interface{}) (bool, []byte, error)
EnsureProperties writes all the properties in 'to_assign' to 'body' if they are absent or contain a new value.
func CessateRecord ¶
CessateRecord will assign the relevant properties to make 'old_body' as cessated (ceased) using the current time.
func CessateRecordWithTime ¶
func CessateRecordWithTime(ctx context.Context, ex Exporter, t time.Time, old_body []byte) ([]byte, error)
CessateRecordWithTime will assign the relevant properties to make 'old_body' as cessated (ceased) using the time defined by 't'.
func DeprecateRecord ¶
DeprecateRecord will assign the relevant properties to make 'old_body' as deprecated using the current time. This method does not handle assigning or updating "supersedes" or "superseded_by" properties.
func DeprecateRecordWithTime ¶
func DeprecateRecordWithTime(ctx context.Context, ex Exporter, t time.Time, old_body []byte) ([]byte, error)
DeprecateRecordWithTime will assign the relevant properties to make 'old_body' as deprecated using the time defined by 't'. This method does not handle assigning or updating "supersedes" or "superseded_by" properties.
func EnsureProperties ¶
func EnsureProperties(ctx context.Context, body []byte, to_ensure map[string]interface{}) ([]byte, error)
EnsureProperties ensure that all the properties in 'to_ensure' are present in 'body', assigning them if necessary.
func Export ¶
Export will perform all the steps necessary to "export" (as in create or update) 'feature' taking care to ensure correct formatting, default values and validation. It returns a boolean value indicating whether the feature was changed during the export process.
func ExporterSchemes ¶
func ExporterSchemes() []string
ExporterSchemes returns list of registered `Exporter` schemes which have been registered.
func HasChanges ¶ added in v3.2.0
HasChanges returns a boolean value indicating whether 'old_feature' and 'new_feature' have changes (indepedent of timestamps).
func PrepareAltFeatureWithoutTimestamps ¶
PrepareAltFeatureWithoutTimestamps ensures the presence of necessary field and/or default values for a Who's On First "alternate geometry" feature record absent the `wof:lastmodified` property. This is to enable checking whether a feature record being exported has been changed.
func PrepareFeatureWithoutTimestamps ¶
PrepareFeatureWithoutTimestamps ensures the presence of necessary field and/or default values for a Who's On First feature record absent the `wof:lastmodified` property. This is to enable checking whether a feature record being exported has been changed.
func PrepareTimestamps ¶
PrepareTimestamps ensure that 'feature' has all the necessary timestamp-related properties assigning default values where necessary.
func RegisterExporter ¶
func RegisterExporter(ctx context.Context, scheme string, init_func ExporterInitializationFunc) error
func RemoveProperties ¶
RemoveProperties removes all the properties in 'to_remove' from 'body'.
func RemovePropertiesIfChanged ¶ added in v3.1.0
func RemovePropertiesIfChanged(ctx context.Context, body []byte, to_remove []string) (bool, []byte, error)
RemovePropertiesIfChanged filters 'to_remove' to ensure they are present in 'body' before removing them.
func SupersedeRecord ¶
func WriteExportIfChanged ¶
Export will perform all the steps necessary to "export" (as in create or update) 'feature' taking care to ensure correct formatting, default values and validation writing data to 'wr' if the feature has been updated. It returns a boolean value indicating whether the feature was changed during the export process.
Types ¶
type Exporter ¶
type Exporter interface {
// Export will perform all the steps necessary to "export" (as in create or update) a Who's On First feature record taking care to ensure correct formatting, default values and validation. It returns a boolean value indicating whether the feature was changed during the export process.
Export(context.Context, []byte) (bool, []byte, error)
}
The `Exporter` interface provides a common interface to allow for customized export functionality in your code which can supplement the default export functionality with application-specific needs.
func NewExporter ¶
NewExporter returns a new `Exporter` instance derived from 'uri'.
Source Files
Directories