From 3d83ed07fdcd52d927caa07170b0b04c0d08d154 Mon Sep 17 00:00:00 2001 From: Slava Pestov Date: Fri, 14 Nov 2008 22:49:17 -0600 Subject: [PATCH] Minor documentation updates: json, xml, serialize --- basis/json/reader/reader-docs.factor | 10 +++++-- basis/json/writer/writer-docs.factor | 10 +++++-- basis/serialize/serialize-docs.factor | 38 ++++++++++++++++++--------- basis/serialize/serialize.factor | 4 +++ basis/xml/xml-docs.factor | 8 +++--- 5 files changed, 48 insertions(+), 22 deletions(-) diff --git a/basis/json/reader/reader-docs.factor b/basis/json/reader/reader-docs.factor index ea4dcbf954..4700423db5 100644 --- a/basis/json/reader/reader-docs.factor +++ b/basis/json/reader/reader-docs.factor @@ -3,6 +3,12 @@ USING: help.markup help.syntax ; IN: json.reader -HELP: json> "( string -- object )" -{ $values { "string" "a string in JSON format" } { "object" "yhe object deserialized from the JSON string" } } +HELP: json> ( string -- object ) +{ $values { "string" "a string in JSON format" } { "object" "a deserialized object" } } { $description "Deserializes the JSON formatted string into a Factor object. JSON objects are converted to Factor hashtables. All other JSON objects convert to their obvious Factor equivalents." } ; + +ARTICLE: "json.reader" "JSON reader" +"The " { $vocab-link "json.reader" } " vocabulary defines a word for parsing strings in JSON format." +{ $subsection json> } ; + +ABOUT: "json.reader" diff --git a/basis/json/writer/writer-docs.factor b/basis/json/writer/writer-docs.factor index 21aa8b2cb5..8512d80384 100644 --- a/basis/json/writer/writer-docs.factor +++ b/basis/json/writer/writer-docs.factor @@ -3,13 +3,19 @@ USING: help.markup help.syntax ; IN: json.writer -HELP: >json "( obj -- string )" +HELP: >json { $values { "obj" "an object" } { "string" "the object converted to JSON format" } } { $description "Serializes the object into a JSON formatted string." } { $see-also json-print } ; -HELP: json-print "( obj -- )" +HELP: json-print { $values { "obj" "an object" } } { $description "Serializes the object into a JSON formatted string and outputs it to the standard output stream." } { $see-also >json } ; +ARTICLE: "json.writer" "JSON writer" +"The " { $vocab-link "json.writer" } " vocabulary defines words for converting objects to JSON format." +{ $subsection >json } +{ $subsection json-print } ; + +ABOUT: "json.writer" diff --git a/basis/serialize/serialize-docs.factor b/basis/serialize/serialize-docs.factor index fc060d6b33..34922a5eae 100644 --- a/basis/serialize/serialize-docs.factor +++ b/basis/serialize/serialize-docs.factor @@ -1,22 +1,34 @@ ! Copyright (C) 2006 Chris Double. ! See http://factorcode.org/license.txt for BSD license. -USING: help.syntax help.markup ; +USING: help.syntax help.markup byte-arrays io ; IN: serialize HELP: serialize -{ $values { "obj" "object to serialize" } -} -{ $description "Serializes the object to the current output stream. Object references within the structure being serialized are maintained." } -{ $examples - { $example "USING: serialize io.encodings.binary io.streams.byte-array prettyprint ;" "binary [ { 1 2 } serialize ] with-byte-writer\n\nbinary [ deserialize ] with-byte-reader ." "{ 1 2 }" } -} -{ $see-also deserialize } ; +{ $values { "obj" "object to serialize" } } +{ $description "Serializes the object to " { $link output-stream } "." } ; HELP: deserialize -{ $values { "obj" "deserialized object" } +{ $values { "obj" "deserialized object" } } +{ $description "Deserializes an object by reading from " { $link input-stream } "." } ; + +HELP: object>bytes +{ $values { "obj" "object to serialize" } { "bytes" byte-array } } -{ $description "Deserializes an object by reading from the current input stream. Object references within the structure that was originally serialized are maintained." } -{ $examples - { $example "USING: serialize io.encodings.binary io.streams.byte-array prettyprint ;" "binary [ { 1 2 } serialize ] with-byte-writer\n\nbinary [ deserialize ] with-byte-reader ." "{ 1 2 }" } +{ $description "Serializes the object to a byte array." } ; + +HELP: bytes>object +{ $values { "bytes" byte-array } { "obj" "deserialized object" } } -{ $see-also serialize } ; +{ $description "Deserializes an object from a byte array." } ; + +ARTICLE: "serialize" "Binary object serialization" +"The " { $vocab-link "serialize" } " vocabulary implements binary serialization for all Factor data types except for continuations. Unlike the prettyprinter, shared structure and circularity is preserved." +$nl +"Storing objects on streams:" +{ $subsection serialize } +{ $subsection deserialize } +"Storing objects as byte arrays:" +{ $subsection object>bytes } +{ $subsection bytes>object } ; + +ABOUT: "serialize" diff --git a/basis/serialize/serialize.factor b/basis/serialize/serialize.factor index 52c1535886..2e72fa12cf 100644 --- a/basis/serialize/serialize.factor +++ b/basis/serialize/serialize.factor @@ -15,6 +15,8 @@ locals prettyprint compiler.units sequences.private classes.tuple.private ; IN: serialize + + : deserialize ( -- obj ) ! [ V{ } clone deserialized diff --git a/basis/xml/xml-docs.factor b/basis/xml/xml-docs.factor index 6a2ff1109e..248a43ed63 100644 --- a/basis/xml/xml-docs.factor +++ b/basis/xml/xml-docs.factor @@ -460,10 +460,8 @@ ARTICLE: { "xml" "entities" } "XML entities" { $subsection with-entities } { $subsection with-html-entities } ; -ARTICLE: { "xml" "intro" } "XML" - "The XML module attempts to implement the XML 1.1 standard, converting strings of text into XML and vice versa. It currently is a work in progress." - $nl - "The XML module was implemented by Daniel Ehrenberg, with contributions from the Factor community" +ARTICLE: "xml" "XML parser" +"The " { $vocab-link "xml" } " vocabulary implements the XML 1.1 standard, converting strings of text into XML and vice versa." { $subsection { "xml" "reading" } } { $subsection { "xml" "writing" } } { $subsection { "xml" "classes" } } @@ -476,4 +474,4 @@ ARTICLE: { "xml" "intro" } "XML" IN: xml -ABOUT: { "xml" "intro" } +ABOUT: "xml"