colors: merge colors.constants and colors.hex.

[factor.git] / basis / colors / colors-docs.factor

diff --git a/basis/colors/colors-docs.factor b/basis/colors/colors-docs.factor
index 95c9782aa7859e33528ff3aa940cd900224ab33c..dea28c433219b689d7408e9056f0c1145c9e7bcb 100644 (file)
--- a/basis/colors/colors-docs.factor
+++ b/basis/colors/colors-docs.factor
@@ -1,5 +1,5 @@
+USING: accessors help.markup help.syntax strings ;
 IN: colors
-USING: accessors help.markup help.syntax ;
 
 HELP: color
 { $class-description "The class of colors. Implementations include " { $link rgba } ", " { $vocab-link "colors.gray" } " and " { $vocab-link "colors.hsv" } "." } ;
@@ -11,6 +11,43 @@ HELP: >rgba
 { $values { "color" color } { "rgba" rgba } }
 { $contract "Converts a color to an RGBA color." } ;
 
+HELP: named-color
+{ $values { "name" string } { "color" color } }
+{ $description "Outputs a named color from the color database." }
+{ $notes "In most cases, " { $link POSTPONE: COLOR: } " should be used instead." }
+{ $errors "Throws an error if the color is not listed in " { $snippet "rgb.txt" } ", " { $snippet "factor-colors.txt" } " or " { $snippet "solarized-colors.txt" } "." } ;
+
+HELP: named-colors
+{ $values { "keys" "a sequence of strings" } }
+{ $description "Outputs a sequence of all colors in the " { $snippet "rgb.txt" } " database." } ;
+
+HELP: parse-color
+{ $values { "str" string } { "color" color } }
+{ $description "Parses a string as a named value or as a hexadecimal value." }
+{ $examples
+    { $example
+        "USING: colors prettyprint ;"
+        "COLOR: sky-blue ."
+        "COLOR: sky-blue"
+    }
+    { $example
+        "USING: colors prettyprint ;"
+        "COLOR: #336699 ."
+        "COLOR: #336699"
+    }
+} ;
+
+HELP: COLOR:
+{ $syntax "COLOR: string" }
+{ $description "Parses as a " { $link color } " object using " { $link parse-color } "." }
+{ $errors "Throws an error if the color is not able to be parsed." }
+{ $examples
+  { $code
+    "USING: colors io.styles ;"
+    "\"Hello!\" { { foreground COLOR: cyan } } format nl"
+  }
+} ;
+
 ARTICLE: "colors.protocol" "Color protocol"
 "Abstract superclass for colors:"
 { $subsections color }
@@ -20,6 +57,15 @@ $nl
 $nl
 "Overriding the accessors is purely an optimization, since the default implementations call " { $link >rgba } " and then extract the appropriate component of the result." ;
 
+ARTICLE: "colors.constants" "Standard color database"
+"The " { $vocab-link "colors" } " vocabulary bundles the X11 " { $snippet "rgb.txt" } " database and Factor's " { $snippet "factor-colors.txt" } " theme database to provide words for looking up color values by name."
+{ $subsections
+    named-color
+    named-colors
+    parse-color
+    POSTPONE: COLOR:
+} ;
+
 ARTICLE: "colors" "Colors"
 "The " { $vocab-link "colors" } " vocabulary defines a protocol for colors, with a concrete implementation for RGBA colors. This vocabulary is used by " { $vocab-link "io.styles" } ", " { $vocab-link "ui" } " and other vocabularies, but it is independent of them."
 $nl