Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add class and method documentation #7

Merged
merged 1 commit into from
Mar 23, 2021
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 12 additions & 0 deletions src/geojson/coordinates.cr
Original file line number Diff line number Diff line change
@@ -1,25 +1,37 @@
module GeoJSON
# A `Coordinates` is a position in longitude, latitude, and (optionally)
# altitude.
#
# This class corresponds to the [GeoJSON Position](https://tools.ietf.org/html/rfc7946#section-3.1.1).
class Coordinates
getter coordinates : Array(Float64)

# Creates a new `Coordinates` with the given *coordinates* array.
def initialize(@coordinates : Array(Float64))
raise_if_invalid
end

# Deserializes a `Coordinates` from the given JSON *parser*.
def initialize(parser : JSON::PullParser)
@coordinates = Array(Float64).new(parser)

raise_if_invalid
end

# Gets this Coordinates' longitude in decimal degrees according to WGS84.
def longitude
coordinates[0]
end

# Gets this Coordinates' latitude in decimal degrees according to WGS84.
def latitude
coordinates[1]
end

# Gets this Coordinates' altitude.
#
# Technically, this positional value is meant to be the height in meters
# above the WGS84 ellipsoid.
def altitude
coordinates[2]?
end
Expand Down
4 changes: 4 additions & 0 deletions src/geojson/exception.cr
Original file line number Diff line number Diff line change
@@ -1,4 +1,8 @@
module GeoJSON
# Raised when an attempt is made to create a GeoJSON object that is malformed.
#
# In most cases, this means that the given coordinates for a geometry object
# don't fulfill the requirements for that geometry type.
class Exception < Exception
end
end
9 changes: 8 additions & 1 deletion src/geojson/feature.cr
Original file line number Diff line number Diff line change
@@ -1,18 +1,25 @@
require "./object"

module GeoJSON
# https://tools.ietf.org/html/rfc7946#section-3.2
# A `Feature` represents a [GeoJSON Feature object](https://tools.ietf.org/html/rfc7946#section-3.2)
# with a geometry and properties.
class Feature < Object
# Gets this Feature's GeoJSON type ("Feature")
getter type : String = "Feature"

@[JSON::Field(emit_null: true)]
# Gets this Feature's geometry.
getter geometry : GeoJSON::Object::Type?

@[JSON::Field(emit_null: true)]
# Gets this Feature's properties.
getter properties : Hash(String, JSON::Any::Type)?

# Gets this Feature's id.
getter id : String | Int32 | Nil

# Creates a new `Feature` with the given *geometry* and optional
# *properties*, *id*, and bounding box *bbox*.
def initialize(@geometry, @properties = nil, *, @id = nil, @bbox = nil)
end
end
Expand Down
6 changes: 5 additions & 1 deletion src/geojson/feature_collection.cr
Original file line number Diff line number Diff line change
@@ -1,10 +1,14 @@
module GeoJSON
# https://tools.ietf.org/html/rfc7946#section-3.3
# A `FeatureCollection` represents a [GeoJSON FeatureCollection object](https://tools.ietf.org/html/rfc7946#section-3.3)
# and contains one or more `Feature`s.
class FeatureCollection < Object
# Gets this FeatureCollection's GeoJSON type ("FeatureCollection")
getter type : String = "FeatureCollection"

# Returns this `FeatureCollections` array of features.
getter features : Array(Feature)

# Creates a new `FeatureCollection` with the given *features*.
def initialize(@features : Array(Feature), *, @bbox = nil)
end
end
Expand Down
14 changes: 13 additions & 1 deletion src/geojson/geometry_collection.cr
Original file line number Diff line number Diff line change
@@ -1,14 +1,26 @@
module GeoJSON
# https://tools.ietf.org/html/rfc7946#section-3.1.8
# A `GeometryCollection` represents a collection of several geometries.
#
# Its array of geometries can contain `Point`, `MultiPoint`, `LineString`,
# `MultiLineString`, `Polygon`, and `MultiPolygon`. Technically, you can nest
# `GeometryCollection`s inside one another, but this is discouraged by the
# specification.
#
# This class corresponds to the [GeoJSON GeometryCollection](https://tools.ietf.org/html/rfc7946#section-3.1.8).
class GeometryCollection < Object
# Gets this GeometryCollection's GeoJSON type ("GeometryCollection")
getter type : String = "GeometryCollection"

# Returns an array of the geometries in this `GeometryCollection`
getter geometries : Array(GeoJSON::Object::Type) = Array(GeoJSON::Object::Type).new

# Creates a new `GeometryCollection` containing the given *geometries* and
# optional bounding box *bbox*.
def initialize(geometries : Array(GeoJSON::Object::Type), *, @bbox = nil)
@geometries += geometries
end

# Deserializes a `GeometryCollection` from the given JSON *parser*.
def self.new(pull : JSON::PullParser)
geometries = [] of GeoJSON::Object::Type
pull.read_begin_object
Expand Down
12 changes: 11 additions & 1 deletion src/geojson/line_string.cr
Original file line number Diff line number Diff line change
@@ -1,22 +1,32 @@
module GeoJSON
# https://tools.ietf.org/html/rfc7946#section-3.1.4
# A `LineString` is a `Geometry` representing two or more points in geographic
# space connected consecutively by lines.
#
# This class corresponds to the [GeoJSON LineString](https://tools.ietf.org/html/rfc7946#section-3.1.4).
class LineString < Object
# Gets this LineString's GeoJSON type ("LineString")
getter type : String = "LineString"

# Gets this LineString's GeoJSON type ("LineString")
getter coordinates : Array(Coordinates)

# Gets the LineString vertex at the given index.
delegate "[]", to: coordinates

# Create a new `LineString` with the given *coordinates* and optional
# bounding box *bbox*.
def initialize(@coordinates : Array(Coordinates), *, @bbox = nil)
raise_if_invalid
end

# :ditto:
def initialize(coordinates : Array(Point), *, @bbox = nil)
@coordinates = coordinates.map { |point| point.coordinates }

raise_if_invalid
end

# :ditto:
def initialize(coordinates : Array(Array(Float64)), *, @bbox = nil)
@coordinates = coordinates.map { |e| Coordinates.new(e) }

Expand Down
12 changes: 11 additions & 1 deletion src/geojson/multi_line_string.cr
Original file line number Diff line number Diff line change
@@ -1,26 +1,36 @@
module GeoJSON
# https://tools.ietf.org/html/rfc7946#section-3.1.5
# A `MultiLineString` is a `Geometry` representing several `LineString`s.
#
# This class corresponds to the [GeoJSON MultiLineString](https://tools.ietf.org/html/rfc7946#section-3.1.5).
class MultiLineString < Object
# Gets this MultiLineString's GeoJSON type ("MultiLineString")
getter type : String = "MultiLineString"

# Returns an array of this MultiLineString's coordinates.
getter coordinates : Array(Array(GeoJSON::Coordinates))

# Gets the `LineString` at the given index.
delegate "[]", to: coordinates

# Create a new `MultiLineString` with the given *coordinates* and optional
# bounding box *bbox*.
def initialize(coordinates : Array(LineString), *, @bbox = nil)
@coordinates = coordinates.map(&.coordinates)
end

# :ditto:
def initialize(coordinates : Array(Array(Array(Float64))), *, @bbox = nil)
@coordinates = coordinates.map do |arry|
LineString.new(arry).coordinates
end
end

# Adds the given *line_string* to this MultiLineString.
def <<(line_string : Array(LineString))
@coordinates << line_string
end

# Adds the given *coordinate* to this MultiLineString.
def <<(coordinate : Array(Array(Float64)))
@coordinates << LineString.new(coordinate).coordinates
end
Expand Down
12 changes: 11 additions & 1 deletion src/geojson/multi_point.cr
Original file line number Diff line number Diff line change
@@ -1,26 +1,36 @@
module GeoJSON
# https://tools.ietf.org/html/rfc7946#section-3.1.3
# A `MultiPoint` is a `Geometry` representing several `Point`s.
#
# This class corresponds to the [GeoJSON MultiPoint](https://tools.ietf.org/html/rfc7946#section-3.1.3).
class MultiPoint < Object
# Gets this MultiPoint's GeoJSON type ("MultiPoint")
getter type : String = "MultiPoint"

# Returns an array of this MultiPoint's coordinates.
getter coordinates : Array(Coordinates)

# Gets the `Point` at the given index.
delegate "[]", to: coordinates

# Create a new `MultiPoint` with the given *coordinates* and optional
# bounding box *bbox*.
def initialize(coordinates : Array(Point), *, @bbox = nil)
@coordinates = coordinates.map(&.coordinates)
end

# :ditto:
def initialize(coordinates : Array(Array(Float64)), *, @bbox = nil)
@coordinates = coordinates.map do |coordinates|
Point.new(coordinates).coordinates
end
end

# Adds the given *point* to this MultiPoint.
def <<(point : Array(Point))
@coordinates << point.coordinates
end

# Adds the given *coordinate* to this MultiPoint.
def <<(coordinate : Array(Float64))
@coordinates << Point.new(coordinate).coordinates
end
Expand Down
12 changes: 11 additions & 1 deletion src/geojson/multi_polygon.cr
Original file line number Diff line number Diff line change
@@ -1,26 +1,36 @@
module GeoJSON
# https://tools.ietf.org/html/rfc7946#section-3.1.7
# A `MultiPolygon` is a `Geometry` representing several `Polygon`s.
#
# This class corresponds to the [GeoJSON MultiPolygon](https://tools.ietf.org/html/rfc7946#section-3.1.7).
class MultiPolygon < Object
# Gets this MultiPolygon's GeoJSON type ("MultiPolygon")
getter type : String = "MultiPolygon"

# Returns an array of this MultiPolygon's coordinates.
getter coordinates : Array(Array(Array(GeoJSON::Coordinates)))

# Gets the `Polygon` at the given index.
delegate "[]", to: coordinates

# Create a new `MultiPolygon` with the given *coordinates* and optional
# bounding box *bbox*.
def initialize(coordinates : Array(Polygon), *, @bbox = nil)
@coordinates = coordinates.map(&.coordinates)
end

# :ditto:
def initialize(coordinates : Array(Array(Array(Array(Float64)))), *, @bbox = nil)
@coordinates = coordinates.map do |arry|
Polygon.new(arry).coordinates
end
end

# Adds the given *polygon* to this MultiPolygon.
def <<(polygon : Array(Polygon))
@coordinates << polygon.coordinates
end

# Adds the given *coordinate* to this MultiPolygon.
def <<(coordinate : Array(Array(Array(Float64))))
@coordinates << Polygon.new(coordinate).coordinates
end
Expand Down
18 changes: 17 additions & 1 deletion src/geojson/point.cr
Original file line number Diff line number Diff line change
@@ -1,10 +1,17 @@
module GeoJSON
# https://tools.ietf.org/html/rfc7946#section-3.1.2
# A `Point` is a `Geometry` representing a single `Position` in geographic
# space.
#
# This class corresponds to the [GeoJSON Point](https://tools.ietf.org/html/rfc7946#section-3.1.2).
class Point < Object
# Gets this Point's GeoJSON type ("Point")
getter type : String = "Point"

# Returns this Point's coordinates.
getter coordinates : Coordinates

# Creates a new `Point` at the given *longitude*, *latitude*, and optional
# *altitude*, and with optional bounding box *bbox*.
def initialize(*, longitude, latitude, altitude = nil, @bbox = nil)
if altitude
@coordinates = Coordinates.new([longitude, latitude, altitude])
Expand All @@ -13,15 +20,24 @@ module GeoJSON
end
end

# Creates a new `Point` with the given *coordinates* and optional bounding
# box *bbox*.
def initialize(@coordinates : GeoJSON::Coordinates, *, @bbox = nil)
end

# :ditto:
def initialize(coordinates : Array(Float64), *, @bbox = nil)
@coordinates = GeoJSON::Coordinates.new(coordinates)
end

# Gets this Point's longitude in decimal degrees according to WGS84.
delegate longitude, to: coordinates
# Gets this Point's latitude in decimal degrees according to WGS84.
delegate latitude, to: coordinates
# Gets this Point's altitude.
#
# Technically, this positional value is meant to be the height in meters
# above the WGS84 ellipsoid.
delegate altitude, to: coordinates

def_equals_and_hash coordinates
Expand Down
11 changes: 10 additions & 1 deletion src/geojson/polygon.cr
Original file line number Diff line number Diff line change
@@ -1,14 +1,22 @@
module GeoJSON
# https://tools.ietf.org/html/rfc7946#section-3.1.6
# A `Polygon` is a `Geometry` representing a closed geometric figure in
# geographic space with optional holes within it.
#
# This class corresponds to the [GeoJSON Polygon](https://tools.ietf.org/html/rfc7946#section-3.1.6).
class Polygon < Object
# Gets this Polygon's GeoJSON type ("Polygon")
getter type : String = "Polygon"

# Returns this Polygon's linear ring coordinates.
getter coordinates : Array(Array(Coordinates))

# Creates a new `Polygon` with the given *coordinates* and optional bounding
# box *bbox*.
def initialize(@coordinates : Array(Array(Coordinates)), *, @bbox = nil)
raise_if_invalid
end

# :ditto:
def initialize(coordinates : Array(Array(Point)), *, @bbox = nil)
@coordinates = coordinates.map do |ring|
ring.map { |point| point.coordinates }
Expand All @@ -17,6 +25,7 @@ module GeoJSON
raise_if_invalid
end

# :ditto:
def initialize(coordinates : Array(Array(Array(Float64))), *, @bbox = nil)
@coordinates = coordinates.map do |ring|
ring.map { |e| Coordinates.new(e) }
Expand Down