From 984044acafcaa558ea6cdc16817d0a5869a70388 Mon Sep 17 00:00:00 2001 From: Blacksmoke16 Date: Sun, 28 Oct 2018 18:57:32 -0400 Subject: [PATCH 1/5] Add SemanticVersion to API docs Add additional method docs --- src/docs_main.cr | 1 + src/semantic_version.cr | 57 ++++++++++++++++++++++++++++++++++++----- 2 files changed, 52 insertions(+), 6 deletions(-) diff --git a/src/docs_main.cr b/src/docs_main.cr index 6693399d45dd..e535d07b79de 100644 --- a/src/docs_main.cr +++ b/src/docs_main.cr @@ -50,6 +50,7 @@ require "./option_parser" require "./partial_comparable" require "./random/**" require "./readline" +require "./semantic_version" require "./signal" require "./string_pool" require "./string_scanner" diff --git a/src/semantic_version.cr b/src/semantic_version.cr index d97c248e3d9e..118ae2ee28d1 100644 --- a/src/semantic_version.cr +++ b/src/semantic_version.cr @@ -1,14 +1,31 @@ # Conforms to Semantic Versioning 2.0.0 -# See http://semver.org/ for more information. +# See [https://semver.org/](https://semver.org/) for more information. class SemanticVersion include Comparable(self) + # The major version of this semantic version getter major : Int32 + + # The minor version of this semantic version getter minor : Int32 + + # The patch version of this semantic version getter patch : Int32 + + # The build number of this semantic version getter build : String? + + # The pre-release metadata of this semantic version getter prerelease : Prerelease + # Parses a `SemanticVersion` from the given semantic version string + # + # ``` + # require "semantic_version" + # + # semver = SemanticVersion.parse("2.61.4") + # semver # => # + # ``` def self.parse(str : String) : self m = str.match /^(\d+)\.(\d+)\.(\d+)(-([\w\.]+))?(\+(\w+))??$/ if m @@ -23,6 +40,7 @@ class SemanticVersion end end + # Create a new `SemanticVersion` instance with the given major, minor, and patch versions def initialize(@major : Int, @minor : Int, @patch : Int, prerelease : String | Prerelease | Nil = nil, @build : String? = nil) @prerelease = case prerelease when Prerelease @@ -36,7 +54,13 @@ class SemanticVersion end end - def to_s(io : IO) + # Returns the string representation of this semantic version + # + # ``` + # semver = SemanticVersion.parse("0.27.1") + # semver.to_s # => "0.27.1" + # ``` + def to_s(io : IO) : String io << major << '.' << minor << '.' << patch unless prerelease.identifiers.empty? io << '-' @@ -47,13 +71,14 @@ class SemanticVersion end end + # :nodoc: def <=>(other : self) : Int32 r = major <=> other.major - return r if r != 0 + return r unless r.zero? r = minor <=> other.minor - return r if r != 0 + return r unless r.zero? r = patch <=> other.patch - return r if r != 0 + return r unless r.zero? pre1 = prerelease pre2 = other.prerelease @@ -61,7 +86,16 @@ class SemanticVersion prerelease <=> other.prerelease end + # Contains additional pre-release metadata related to this semantic version struct Prerelease + # Parses a `Prerelease` from the given pre-release metadata string + # + # ``` + # require "semantic_version" + # + # prerelease = SemanticVersion::Prerelease.parse("rc.1.3") + # prerelease # => SemanticVersion::Prerelease(@identifiers=["rc", 1, 3]) + # ``` def self.parse(str : String) : self identifiers = [] of String | Int32 str.split('.').each do |val| @@ -74,15 +108,26 @@ class SemanticVersion Prerelease.new identifiers end + # Array of identifiers that make up the pre-release metadata getter identifiers : Array(String | Int32) + # Create a new `Prerelease` instance with supplied array of identifiers def initialize(@identifiers : Array(String | Int32) = [] of String | Int32) end - def to_s(io : IO) + # Returns the string representation of this semantic version's pre-release metadata + # + # ``` + # require "semantic_version" + # + # semver = SemanticVersion.parse("0.27.1-rc.1") + # semver.prerelease.to_s # => "rc.1" + # ``` + def to_s(io : IO) : String identifiers.join(".", io) end + # :nodoc: def <=>(other : self) : Int32 if identifiers.empty? if other.identifiers.empty? From 887e42c86e4f3bc5fd84cb8e39c655c0dcf77e53 Mon Sep 17 00:00:00 2001 From: Blacksmoke16 Date: Sun, 28 Oct 2018 19:19:04 -0400 Subject: [PATCH 2/5] Fix spec --- src/semantic_version.cr | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/semantic_version.cr b/src/semantic_version.cr index 118ae2ee28d1..e94c6983d994 100644 --- a/src/semantic_version.cr +++ b/src/semantic_version.cr @@ -60,7 +60,7 @@ class SemanticVersion # semver = SemanticVersion.parse("0.27.1") # semver.to_s # => "0.27.1" # ``` - def to_s(io : IO) : String + def to_s(io : IO) io << major << '.' << minor << '.' << patch unless prerelease.identifiers.empty? io << '-' @@ -123,7 +123,7 @@ class SemanticVersion # semver = SemanticVersion.parse("0.27.1-rc.1") # semver.prerelease.to_s # => "rc.1" # ``` - def to_s(io : IO) : String + def to_s(io : IO) identifiers.join(".", io) end From 60ecb6a8c60a43d2046b1dfbe27477c9eee2d5ed Mon Sep 17 00:00:00 2001 From: Blacksmoke16 Date: Mon, 29 Oct 2018 10:38:39 -0400 Subject: [PATCH 3/5] Address comments --- src/semantic_version.cr | 40 +++++++++++++++++++++++++++++++++++----- 1 file changed, 35 insertions(+), 5 deletions(-) diff --git a/src/semantic_version.cr b/src/semantic_version.cr index e94c6983d994..fe814f9f07a2 100644 --- a/src/semantic_version.cr +++ b/src/semantic_version.cr @@ -1,4 +1,5 @@ # Conforms to Semantic Versioning 2.0.0 +# # See [https://semver.org/](https://semver.org/) for more information. class SemanticVersion include Comparable(self) @@ -12,7 +13,7 @@ class SemanticVersion # The patch version of this semantic version getter patch : Int32 - # The build number of this semantic version + # The build metadata of this semantic version getter build : String? # The pre-release metadata of this semantic version @@ -26,6 +27,8 @@ class SemanticVersion # semver = SemanticVersion.parse("2.61.4") # semver # => # # ``` + # + # Raises `ArgumentError` if *str* is not a semantic version. def self.parse(str : String) : self m = str.match /^(\d+)\.(\d+)\.(\d+)(-([\w\.]+))?(\+(\w+))??$/ if m @@ -40,7 +43,10 @@ class SemanticVersion end end - # Create a new `SemanticVersion` instance with the given major, minor, and patch versions + # Creates a new `SemanticVersion` instance with the given major, minor, and patch versions + # and optionally build and pre-release metadata + # + # Raises `ArgumentError` if *prerelease* is invalid pre-release metadata. def initialize(@major : Int, @minor : Int, @patch : Int, prerelease : String | Prerelease | Nil = nil, @build : String? = nil) @prerelease = case prerelease when Prerelease @@ -57,6 +63,8 @@ class SemanticVersion # Returns the string representation of this semantic version # # ``` + # require "semantic_version" + # # semver = SemanticVersion.parse("0.27.1") # semver.to_s # => "0.27.1" # ``` @@ -71,7 +79,18 @@ class SemanticVersion end end - # :nodoc: + # The comparison operator + # + # ``` + # require "semantic_version" + # + # semver1 = SemanticVersion.new(1, 0, 0) + # semver2 = SemanticVersion.new(2, 0, 0) + # + # semver1 <=> semver2 # => -1 + # semver2 <=> semver2 # => 0 + # semver2 <=> semver1 # => 1 + # ``` def <=>(other : self) : Int32 r = major <=> other.major return r unless r.zero? @@ -111,7 +130,7 @@ class SemanticVersion # Array of identifiers that make up the pre-release metadata getter identifiers : Array(String | Int32) - # Create a new `Prerelease` instance with supplied array of identifiers + # Creates a new `Prerelease` instance with supplied array of identifiers def initialize(@identifiers : Array(String | Int32) = [] of String | Int32) end @@ -127,7 +146,18 @@ class SemanticVersion identifiers.join(".", io) end - # :nodoc: + # The comparison operator + # + # ``` + # require "semantic_version" + # + # prerelease1 = SemanticVersion::Prerelease.new(["rc", 1]) + # prerelease2 = SemanticVersion::Prerelease.new(["rc", 1, 2]) + # + # prerelease1 <=> prerelease2 # => -1 + # prerelease1 <=> prerelease1 # => 0 + # prerelease2 <=> prerelease1 # => 1 + # ``` def <=>(other : self) : Int32 if identifiers.empty? if other.identifiers.empty? From 0968fe384f999cfa2f4297c62f830eeb86e5c142 Mon Sep 17 00:00:00 2001 From: Blacksmoke16 Date: Tue, 30 Oct 2018 10:51:49 -0400 Subject: [PATCH 4/5] Update verbiage --- src/semantic_version.cr | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/semantic_version.cr b/src/semantic_version.cr index fe814f9f07a2..3227f95052f2 100644 --- a/src/semantic_version.cr +++ b/src/semantic_version.cr @@ -16,7 +16,7 @@ class SemanticVersion # The build metadata of this semantic version getter build : String? - # The pre-release metadata of this semantic version + # The pre-release version of this semantic version getter prerelease : Prerelease # Parses a `SemanticVersion` from the given semantic version string From 918d7aabbe4d181ad32a1ed005c5497ec26c9221 Mon Sep 17 00:00:00 2001 From: Blacksmoke16 Date: Tue, 30 Oct 2018 11:12:04 -0400 Subject: [PATCH 5/5] Update other verbiage --- src/semantic_version.cr | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/semantic_version.cr b/src/semantic_version.cr index 3227f95052f2..8909a1d63fd8 100644 --- a/src/semantic_version.cr +++ b/src/semantic_version.cr @@ -44,9 +44,9 @@ class SemanticVersion end # Creates a new `SemanticVersion` instance with the given major, minor, and patch versions - # and optionally build and pre-release metadata + # and optionally build and pre-release version # - # Raises `ArgumentError` if *prerelease* is invalid pre-release metadata. + # Raises `ArgumentError` if *prerelease* is invalid pre-release version def initialize(@major : Int, @minor : Int, @patch : Int, prerelease : String | Prerelease | Nil = nil, @build : String? = nil) @prerelease = case prerelease when Prerelease @@ -105,9 +105,9 @@ class SemanticVersion prerelease <=> other.prerelease end - # Contains additional pre-release metadata related to this semantic version + # Contains the pre-release version related to this semantic version struct Prerelease - # Parses a `Prerelease` from the given pre-release metadata string + # Parses a `Prerelease` from the given pre-release version string # # ``` # require "semantic_version"