From 6e696ffb297ab0066cc4f6deeda0c14b887a89fd Mon Sep 17 00:00:00 2001 From: Kaz Kylheku Date: Sun, 30 May 2021 19:40:25 -0700 Subject: doc: document all json I/O convenience routines. * txr.1: Documented file-get-json, file-put-json, file-append-json, file-get-jsons, file-put-jsons, file-append-jsons, command-get-json, command-put-json, command-get-jsons, command-put-jsons. * share/txr/stdlib/doc-syms.tl: Updated. --- share/txr/stdlib/doc-syms.tl | 182 +++++++++++++++++--------------- txr.1 | 243 +++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 339 insertions(+), 86 deletions(-) diff --git a/share/txr/stdlib/doc-syms.tl b/share/txr/stdlib/doc-syms.tl index 7f3dda77..396905dd 100644 --- a/share/txr/stdlib/doc-syms.tl +++ b/share/txr/stdlib/doc-syms.tl @@ -55,8 +55,8 @@ ("*tree-fun-whitelist*" "N-025AB9C9") ("*unhandled-hook*" "N-02B4A4FB") ("*v" "N-0367AE5A") - ("+" "D-0044") - ("-" "D-004A") + ("+" "D-0045") + ("-" "D-004B") ("--" "N-0234C408") ("--args" "N-03FCDE42") ("--eargs" "N-03FCDE42") @@ -70,29 +70,29 @@ ("-rng+" "N-00BEA6DF") ("-rng-" "N-00BEA6DF") (".." "N-0217A971") - ("..." "D-0034") - ("/" "D-0049") + ("..." "D-0035") + ("/" "D-004A") ("//" "N-0054C409") ("/=" "N-003BE40C") (":key" "N-01697547") (":match" "N-03B92C0D") - ("<" "D-0057") + ("<" "D-0058") ("" "D-0060") - (">=" "D-0053") + ("=" "D-0078") + (">" "D-0061") + (">=" "D-0054") ("TXR_COMPAT" "N-03F5D03D") ("abort" "N-02F934F6") ("abs" "D-0017") ("abs-path-p" "N-00477B23") - ("accept" "D-0043") + ("accept" "D-0044") ("acons" "N-02E9343D") ("acons-new" "N-0371BAFA") ("aconsql-new" "N-01E315BD") ("acos" "D-0028") - ("acosh" "D-0041") + ("acosh" "D-0042") ("add" "N-03244398") ("add*" "N-03244398") ("addrinfo" "N-0110E961") @@ -112,10 +112,10 @@ ("alignof" "N-000F730E") ("alist-nremove" "N-000CD07F") ("alist-remove" "N-001A53C4") - ("all" "D-0054") + ("all" "D-0055") ("all*" "N-00F6E2A2") ("allocate-struct" "N-03168BF2") - ("and" "D-0068") + ("and" "D-0069") ("andf" "N-01E7D2AD") ("ap" "N-00BE749A") ("apf" "N-012A7E6A") @@ -133,20 +133,20 @@ ("array" "N-0117BE95") ("arraysize" "N-002129D6") ("as" "N-028B26DD") - ("ash" "D-0063") - ("asin" "D-003C") + ("ash" "D-0064") + ("asin" "D-003D") ("asinh" "D-0004") - ("assert" "D-005F") + ("assert" "D-0060") ("assoc" "N-00E9306D") ("assq" "N-00123702") ("assql" "N-00123702") ("at-exit-call" "N-003EEEF5") ("at-exit-do-not-call" "N-003EEEF5") - ("atan" "D-0050") + ("atan" "D-0051") ("atan2" "D-000A") ("atanh" "D-0024") ("atom" "N-0076C7BE") - ("awk" "D-0058") + ("awk" "D-0059") ("base-name" "N-02C01721") ("base64-decode" "N-01B05083") ("base64-decode-buf" "N-01B05083") @@ -161,15 +161,15 @@ ("bchar" "N-0008D7DC") ("bignum-len" "N-020294AB") ("bignump" "N-03E9D6E1") - ("bind" "D-006D") + ("bind" "D-006E") ("bindable" "N-0222F2E3") - ("bit" "D-004C") - ("bitset" "D-0037") + ("bit" "D-004D") + ("bitset" "D-0038") ("blkcnt-t" "N-01D716FE") ("blksize-t" "N-01D716FE") - ("block" "D-006F") + ("block" "D-0070") ("block*" "N-02F60DCE") - ("bool" "D-002C") + ("bool" "D-002D") ("boundp" "N-01FBF828") ("bracket" "N-02400F97") ("break-str" "N-00A9DB25") @@ -179,7 +179,7 @@ ("bsdly" "N-03BD477F") ("bstr" "N-00C6B7C4") ("bstr-d" "N-00C6B7C4") - ("buf" "D-005E") + ("buf" "D-005F") ("buf-alloc-size" "N-013A3727") ("buf-carray" "N-0022F54E") ("buf-d" "D-0014") @@ -293,8 +293,8 @@ ("cdar" "N-00209CEE") ("cdddddr" "N-00209CEE") ("cddr" "N-00209CEE") - ("cdr" "D-0076") - ("ceil" "D-007B") + ("cdr" "D-0077") + ("ceil" "D-007C") ("ceil-rem" "N-02DE978F") ("ceil1" "N-02C8FF28") ("chain" "N-00C53CF7") @@ -349,8 +349,8 @@ ("cmp-str" "N-0143A273") ("cmspar" "N-01B1B5DF") ("coded-length" "N-0167F423") - ("coll" "D-0059") - ("collect" "D-002F") + ("coll" "D-005A") + ("collect" "D-0030") ("collect-each" "N-0105F01D") ("collect-each*" "N-0105F01D") ("collect-each-prod" "N-02CA3C70") @@ -358,10 +358,14 @@ ("comb" "N-02E6CEDD") ("command-get" "N-0062A33B") ("command-get-buf" "N-00FA177D") + ("command-get-json" "N-028645A2") + ("command-get-jsons" "N-028645A2") ("command-get-lines" "N-0062A33B") ("command-get-string" "N-0062A33B") ("command-put" "N-024D65F3") ("command-put-buf" "N-02AE3A31") + ("command-put-json" "N-029045AE") + ("command-put-jsons" "N-029045AE") ("command-put-lines" "N-024D65F3") ("command-put-string" "N-024D65F3") ("compare-swap" "N-02933F2A") @@ -402,7 +406,7 @@ ("copy-tree-iter" "N-025C3140") ("copy-vec" "N-010E7635") ("cos" "D-0021") - ("cosh" "D-007E") + ("cosh" "D-0080") ("count-if" "N-00BBC726") ("count-until-match" "N-00EFD668") ("countq" "N-01DF131F") @@ -442,7 +446,7 @@ ("data" "N-03B6EA7D") ("dec" "N-03A0AABD") ("defer-warning" "N-001106AB") - ("defex" "D-005D") + ("defex" "D-005E") ("deffi" "N-00DCE51D") ("deffi-cb" "N-00C54FC8") ("deffi-cb-unsafe" "N-00C54FC8") @@ -489,7 +493,7 @@ ("dlsym-checked" "N-029063A0") ("dlvsym" "N-01B1E865") ("dlvsym-checked" "N-029063A0") - ("do" "D-0071") + ("do" "D-0072") ("doc" "N-0097F54C") ("dohash" "N-039105E8") ("doloop" "N-01FF4DDB") @@ -618,7 +622,7 @@ ("eprototype" "N-036B1BDB") ("eq" "N-02550B35") ("eql" "N-02550B35") - ("equal" "D-0079") + ("equal" "D-007A") ("equot" "N-02ACCDDF") ("erange" "N-036B1BDB") ("erofs" "N-036B1BDB") @@ -640,13 +644,13 @@ ("exec" "N-02D6C913") ("exit" "N-0006C92F") ("exit*" "N-03592671") - ("exp" "D-0035") + ("exp" "D-0036") ("expand" "N-00E0F5F5") ("expand-left" "N-00E168FE") ("expand-right" "N-023B6B64") ("expand-with-free-refs" "N-0334827B") - ("expt" "D-0075") - ("exptmod" "D-0036") + ("expt" "D-0076") + ("exptmod" "D-0037") ("extproc" "N-0072FF5E") ("f" "N-003BDFA9") ("f$" "N-000B5ACD") @@ -699,10 +703,14 @@ ("file-append-string" "N-000CCA8A") ("file-get" "N-02238370") ("file-get-buf" "N-00FA177D") + ("file-get-json" "N-03C963BD") + ("file-get-jsons" "N-03C963BD") ("file-get-lines" "N-02238370") ("file-get-string" "N-02238370") ("file-put" "N-0041C2E5") ("file-put-buf" "N-02AE3A31") + ("file-put-json" "D-002A") + ("file-put-jsons" "D-007D") ("file-put-lines" "N-0041C2E5") ("file-put-string" "N-0041C2E5") ("fileno" "N-008ACF75") @@ -714,7 +722,7 @@ ("filter-equal" "N-03136087") ("filter-string-tree" "N-00C9EEB0") ("finalize" "N-01230613") - ("finally" "D-0078") + ("finally" "D-0079") ("find" "N-005431FF") ("find-frame" "N-02B97226") ("find-frames" "N-02B97226") @@ -817,7 +825,7 @@ ("functionp" "N-00F6F5F8") ("fuzz" "N-03CAE17D") ("fw" "N-0357AE6F") - ("gather" "D-002A") + ("gather" "D-002B") ("gcd" "N-03D44645") ("gen" "N-0323BEBD") ("gen-hash-seed" "N-002CFA72") @@ -826,9 +834,9 @@ ("gequal" "N-00A3E42D") ("get" "N-03D9F55D") ("get-buf-from-stream" "N-02954B48") - ("get-byte" "D-0062") - ("get-char" "D-0065") - ("get-error" "D-0032") + ("get-byte" "D-0063") + ("get-char" "D-0066") + ("get-error" "D-0033") ("get-error-str" "D-0010") ("get-fd" "N-011D42AB") ("get-frames" "N-010405DA") @@ -836,6 +844,7 @@ ("get-indent" "N-024E9FD8") ("get-indent-mode" "N-03F3170C") ("get-json" "N-014295FE") + ("get-jsons" "N-0124D378") ("get-line" "D-0018") ("get-line-as-buf" "N-007FD2F9") ("get-lines" "N-00B65D06") @@ -953,7 +962,7 @@ ("imaxbel" "N-02391683") ("improper-plist-to-alist" "N-006E31B5") ("in" "N-016BE41C") - ("in-package" "D-0072") + ("in-package" "D-0073") ("in-range" "N-02C56FB6") ("in-range*" "N-02C56FB6") ("in6addr-any" "N-026A2C3B") @@ -998,13 +1007,13 @@ ("isatty" "N-03709E8A") ("isec" "N-0385B074") ("isig" "N-0072FF5E") - ("isqrt" "D-0038") + ("isqrt" "D-0039") ("istrip" "N-02391683") - ("iter-begin" "D-002D") + ("iter-begin" "D-002E") ("iter-item" "D-0005") - ("iter-more" "D-003D") + ("iter-more" "D-003E") ("iter-reset" "D-0020") - ("iter-step" "D-0070") + ("iter-step" "D-0071") ("iterable" "N-01156AE3") ("itimer-prof" "N-02B7882A") ("itimer-real" "N-02B7882A") @@ -1033,10 +1042,10 @@ ("kill" "N-0386CCD5") ("krs" "N-02D33A4D") ("labels" "N-0209307D") - ("lambda" "D-002B") + ("lambda" "D-002C") ("lambda-match" "N-031E43FF") ("lambda-set" "N-02FEBA97") - ("last" "D-0042") + ("last" "D-0043") ("lazy-str" "N-02AFF63D") ("lazy-str-force" "N-03269DEF") ("lazy-str-force-upto" "N-0212FED6") @@ -1054,7 +1063,7 @@ ("ldo" "N-03EF3A27") ("left" "N-020D5C1D") ("len" "N-03AD172A") - ("length" "D-0048") + ("length" "D-0049") ("length-buf" "N-0026D89A") ("length-carray" "N-03FF97BD") ("length-list" "N-01F8186A") @@ -1084,11 +1093,11 @@ ("listp" "N-03F70343") ("lnew" "N-0230059D") ("lnew*" "N-021E6FDC") - ("load" "D-007F") + ("load" "D-0081") ("load-for" "N-0020A085") - ("load-time" "D-0047") + ("load-time" "D-0048") ("loff-t" "N-01D716FE") - ("log" "D-0046") + ("log" "D-0047") ("log-alert" "N-035D75EC") ("log-auth" "N-0116F48F") ("log-authpriv" "N-0116F48F") @@ -1107,15 +1116,15 @@ ("log-pid" "N-02371913") ("log-user" "N-0116F48F") ("log-warning" "N-035D75EC") - ("log10" "D-0051") - ("log2" "D-0073") + ("log10" "D-0052") + ("log2" "D-0074") ("logand" "D-000E") - ("logcount" "D-003A") - ("logior" "D-004B") + ("logcount" "D-003B") + ("logior" "D-004C") ("lognot" "D-0012") ("lognot1" "N-019541E2") ("logtest" "N-00B1548A") - ("logtrunc" "D-0074") + ("logtrunc" "D-0075") ("logxor" "N-02D5AF97") ("long" "N-018C7C8C") ("longlong" "N-02299408") @@ -1203,14 +1212,14 @@ ("meq" "N-020A0042") ("meql" "N-020A0042") ("mequal" "N-020A0042") - ("merge" "D-005A") + ("merge" "D-005B") ("merge-delete-package" "N-0160EA2C") ("meth" "N-02C216C3") ("method" "N-022200C1") ("mf" "N-036B6E55") ("min" "N-023C3643") ("minor" "N-02F0F482") - ("minusp" "D-004F") + ("minusp" "D-0050") ("mismatch" "N-03164F4F") ("mkdir" "N-00C543B8") ("mkfifo" "N-0091FD43") @@ -1218,7 +1227,7 @@ ("mkstring" "N-033DD796") ("mlet" "N-008216E0") ("mmakunbound" "N-02964FC0") - ("mod" "D-003F") + ("mod" "D-0040") ("mode-t" "N-01D716FE") ("multi" "N-034946BA") ("multi-sort" "N-0132852F") @@ -1235,7 +1244,7 @@ ("new" "N-0230059D") ("new*" "N-021E6FDC") ("nexpand-left" "N-00E168FE") - ("next" "D-006C") + ("next" "D-006D") ("next-file" "N-00839D2F") ("nf" "N-0267AE6D") ("nil" "N-015134D8") @@ -1246,8 +1255,8 @@ ("nldly" "N-03BD477F") ("nlink-t" "N-01D716FE") ("noflsh" "N-0072FF5E") - ("none" "D-006B") - ("not" "D-0069") + ("none" "D-006C") + ("not" "D-006A") ("notf" "N-0026CE18") ("nr" "N-03A7AE6D") ("nreconc" "N-012FF2DC") @@ -1285,7 +1294,7 @@ ("obtain*-block" "N-0102F0EB") ("obtain-block" "N-01C791D0") ("ocrnl" "N-03BD477F") - ("oddp" "D-0039") + ("oddp" "D-003A") ("ofdel" "N-03BD477F") ("off-t" "N-01D716FE") ("offsetof" "N-013D0A5C") @@ -1371,7 +1380,7 @@ ("placelet" "N-0393C970") ("placelet*" "N-0393C970") ("plist-to-alist" "N-006E31B5") - ("plusp" "D-0067") + ("plusp" "D-0068") ("poll" "N-0386D39D") ("poly" "N-026201AD") ("pop" "N-017F39D2") @@ -1390,7 +1399,7 @@ ("pprof" "N-018C92AB") ("pred" "N-038E636C") ("prinl" "N-02FCCE0D") - ("print" "D-0045") + ("print" "D-0046") ("prn" "N-01E7F5F7") ("prod" "N-0163FFE2") ("prof" "N-004C9B10") @@ -1415,20 +1424,21 @@ ("push" "N-01C211C1") ("pushhash" "N-022660B2") ("pushnew" "N-02C37AB0") - ("put-buf" "D-007D") - ("put-byte" "D-002E") + ("put-buf" "D-007F") + ("put-byte" "D-002F") ("put-carray" "N-00737951") ("put-char" "D-0003") ("put-json" "N-009C27EF") ("put-jsonl" "N-009C27EF") + ("put-jsons" "N-0124CAE6") ("put-line" "N-012163C3") ("put-lines" "N-0367B282") ("put-obj" "N-025DB229") - ("put-string" "D-007A") + ("put-string" "D-007B") ("put-strings" "N-0367B282") ("pwd" "N-0047F5F6") ("qquote" "N-01665185") - ("qref" "D-006E") + ("qref" "D-006F") ("quip" "N-03C6D422") ("quote" "N-0163F998") ("r$" "N-03BBB0C5") @@ -1499,8 +1509,8 @@ ("remqual" "N-000ECD82") ("remqual*" "N-00B85CD2") ("rename-path" "N-016EF40C") - ("rep" "D-004E") - ("repeat" "D-006A") + ("rep" "D-004F") + ("repeat" "D-006B") ("replace" "N-035991E1") ("replace-buf" "N-01C59E4E") ("replace-list" "N-03E43DA2") @@ -1508,7 +1518,7 @@ ("replace-struct" "N-01A8343B") ("replace-tree-iter" "N-01225FF3") ("replace-vec" "N-01F59E62") - ("require" "D-007C") + ("require" "D-007E") ("reset-struct" "N-002A609F") ("rest" "N-02288559") ("ret" "N-033F39EF") @@ -1541,7 +1551,7 @@ ("round-rem" "N-02DE978F") ("round1" "N-03EA1351") ("rperm" "N-0188EBDE") - ("rplaca" "D-004D") + ("rplaca" "D-004E") ("rplacd" "D-0009") ("rpoly" "N-026201AD") ("rpos" "N-01F68300") @@ -1665,10 +1675,10 @@ ("sig-winch" "N-0176430F") ("sig-xcpu" "N-0176430F") ("sig-xfsz" "N-0176430F") - ("sign-extend" "D-0030") + ("sign-extend" "D-0031") ("signum" "D-000F") ("sin" "D-000B") - ("sinh" "D-0066") + ("sinh" "D-0067") ("sixth" "N-01B0FA33") ("size-t" "N-03258244") ("size-vec" "N-01000634") @@ -1697,7 +1707,7 @@ ("sockaddr-in" "N-01DD05D9") ("sockaddr-in6" "N-013DD169") ("sockaddr-un" "N-01DD05D2") - ("some" "D-0040") + ("some" "D-0041") ("sort" "N-01FE5176") ("sort-group" "N-01E65DDC") ("source-loc" "N-0370CD69") @@ -1712,13 +1722,13 @@ ("split-str" "N-000386B4") ("split-str-set" "N-0296195B") ("sqrt" "D-0027") - ("square" "D-0031") + ("square" "D-0032") ("ssize-t" "N-01D716FE") ("sspl" "N-0296195B") ("sssucc" "N-038E636C") ("ssucc" "N-038E636C") ("starts-with" "N-004955D4") - ("stat" "D-005B") + ("stat" "D-005C") ("static-slot" "N-02C47D17") ("static-slot-ensure" "N-02E71F31") ("static-slot-home" "N-01F88B0D") @@ -1800,8 +1810,8 @@ ("take" "N-00F6D433") ("take-until" "N-01E42C4C") ("take-while" "N-01E42C4C") - ("tan" "D-003B") - ("tanh" "D-0061") + ("tan" "D-003C") + ("tanh" "D-0062") ("tb" "N-02AB6E53") ("tc" "N-029B6E53") ("tcdrain" "N-01AC4760") @@ -1833,14 +1843,14 @@ ("test-set-indent-mode" "N-01A1F89C") ("tf" "N-032070EB") ("third" "N-01B0FA33") - ("throw" "D-0052") + ("throw" "D-0053") ("throwf" "N-015466AD") - ("time" "D-0033") + ("time" "D-0034") ("time-fields-local" "N-00789418") ("time-fields-utc" "N-00789418") ("time-local" "N-001284ED") ("time-nsec" "N-03B6DB3D") - ("time-parse" "D-0064") + ("time-parse" "D-0065") ("time-parse-local" "N-00207C99") ("time-parse-utc" "N-00207C99") ("time-string" "N-007B1819") @@ -1868,7 +1878,7 @@ ("touch" "N-0038DD42") ("tprint" "N-0217DE45") ("trace" "N-02833733") - ("trailer" "D-0056") + ("trailer" "D-0057") ("transpose" "N-03AA85AD") ("tree" "N-02F6D50B") ("tree-begin" "N-02887FCA") @@ -1896,7 +1906,7 @@ ("trim-right" "N-00CF29CC") ("trim-str" "N-00E6E63B") ("true" "N-00373D97") - ("trunc" "D-005C") + ("trunc" "D-005D") ("trunc-rem" "N-02DE978F") ("trunc1" "N-02E91F51") ("truncate" "N-0032FBF3") @@ -1931,7 +1941,7 @@ ("umethod" "N-000BCBC5") ("uname" "N-0308D954") ("unget-byte" "D-0007") - ("unget-char" "D-0055") + ("unget-char" "D-0056") ("uni" "N-0385B074") ("unintern" "N-01B6BFC2") ("union" "N-01C78B86") @@ -2051,6 +2061,6 @@ ("zarray" "N-017039ED") ("zchar" "N-0008D7DC") ("zero-fill" "N-016D3BB5") - ("zerop" "D-003E") + ("zerop" "D-003F") ("zip" "N-03AA85AD") ("znew" "N-00B1FC38")))) diff --git a/txr.1 b/txr.1 index 04459f6e..dbe30aac 100644 --- a/txr.1 +++ b/txr.1 @@ -72061,6 +72061,249 @@ If the application produces and expands a macro form which does not conform to this syntax, or does not specify one of the above two quoting symbols, the behavior is unspecified. +.coNP Function @ put-jsons +.synb +.mets (put-jsons < seq >> [ stream <> [ flat-p ]]) +.syne +.desc +The +.code put-jsons +function writes multiple JSON representations into +.metn stream . +The objects are specified by the +.meta seq +argument, which must be an iterable object. The +.code put-jsons +function iterates over +.meta seq +and writes each element to the stream as if by using the +.code put-jsonl +function. Consequently, a newline character is written after each object. + +If the +.meta stream +argument is not specified, the parameter takes on the value of +.metn *stdout* . + +The +.meta flat-p +argument has the same meaning as in +.code put-json +with regard to the individual elements. If it is specified and true, +then exactly as many lines of text are written to +.meta stream +as there are elements in +.metn seq . + +The +.code put-jsons +function returns +.metn t . + +.coNP Function @ get-jsons +.synb +.mets (gut-jsons <> [ stream ]) +.syne +.desc +The +.meta get-jsons +function reads zero or more JSON representations from +.meta stream +until an end-of-stream or error condition is encountered. + +The objects are read as if by calls to +.code get-json +and accumulated into a list. + +If the +.meta stream +argument is omitted, it defaults to +.codn *stdin* . + +If the end-of-stream condition is read, then the list of accumulated objects is +returned. If an error occurs, then an exception is thrown and the list of +accumulated objects is not available. + +If an end-of-stream condition occurs before any character is seen other than +JSON whitespace, then the empty list +.code nil +is returned. + +.coNP Functions @ file-get-json and @ file-get-jsons +.synb +.mets (file-get-json << name ) +.mets (file-get-jsons << name ) +.syne +.desc +The +.code file-get-json +and +.code file-get-jsons +function open a text stream over the file indicated by the string argument +.meta name +for reading. The functions ensure that the stream is closed when +they terminate. + +The +.code file-get-json +function invokes +.code get-json +to read a single JSON object, which is returned if that function +returns normally. + +The +.code file-get-jsons +function invokes +.code get-jsons +to retrieve a list of JSON objects from the stream, which is returned +if that function returns normally. + +.coNP Functions @ file-put-json and @ file-put-jsons +.synb +.mets (file-put-json < obj < name <> [ flat-p ]) +.mets (file-put-jsons < seq < name <> [ flat-p ]) +.syne +.desc +The +.code file-put-json +and +.code file-put-jsons +functions open a text stream over the file indicated by the string argument +.metn name , +using the function +.code open-file +with a +.meta mode-string +argument of +.strn w , +write the argument object into the stream in their specific manner, +and then close the stream. + +The +.code file-put-json +function writes a JSON representation of +.meta obj +using the +.code put-json +function. The +.meta flat-p +argument is passed to that function, defaulting to +.codn nil . +The value returned is that of +.codn put-json . + +The +.code file-put-jsons +function writes zero or more JSON representations of objects from +.metn seq , +which must be an iterable object, using the +.code put-jsons +function. The +.meta flat-p +argument is passed to that function, defaulting to +.codn nil . +The value returned is that of +.codn put-jsons . + +.coNP Functions @ file-put-json and @ file-put-jsons +.synb +.mets (file-append-json < obj < name <> [ flat-p ]) +.mets (file-append-jsons < seq < name <> [ flat-p ]) +.syne +.desc +The +.code file-append-json +and +.code file-append-jsons +are identical in almost all requirements to the functions +.code file-put-json +and +.codn file-put-jsons . + +The only difference is that when these functions open +a text stream using +.codn open-file , +they specify a +.meta mode-string +argument of +.str a +rather than +.strn w , +in order to append data to the target file rather than overwrite it. + +.coNP Functions @ command-get-json and @ command-get-jsons +.synb +.mets (command-get-json << cmd ) +.mets (command-get-jsons << cmd ) +.syne +.desc +The +.code command-get-json +and +.code command-get-jsons +functions opens text stream over an input command pipe created for +the command string +.metn cmd , +as if by the +.code open-command +function. They ensure that the stream is closed when they terminate. + +The +.code command-get-json +function calls +.code get-json +on the stream, and returns the value returned by that function. + +Similarly, +.code command-get-jsons +function calls +.code get-jsons +on the stream, and returns the value returned by that function. + +.coNP Functions @ command-put-json and @ command-put-jsons +.synb +.mets (command-put-json < obj < cmd <> [ flat-p ]) +.mets (command-put-jsons < seq < cmd <> [ flat-p ]) +.syne +.desc +The +.code command-put-json +and +.code command-put-jsons +functions open an output text stream over an output command pipe created +for the command specified in the string argument +.metn cmd , +using the function +.code open-command +function, write the argument object into the stream, in their specific manner, +and then close the stream. + +The +.code command-put-json +function writes a JSON representation of +.meta obj +using the +.code put-json +function. The +.meta flat-p +argument is passed to that function, defaulting to +.codn nil . +The value returned is that of +.codn put-json . + +The +.code command-put-jsons +function writes zero or more JSON representations of objects from +.metn seq , +which must be an iterable object, using the +.code put-jsons +function. The +.meta flat-p +argument is passed to that function, defaulting to +.codn nil . +The value returned is that of +.codn put-jsons . + .SH* FOREIGN FUNCTION INTERFACE On platforms where it is supported, \*(TX provides a feature called the -- cgit v1.2.3