guile-rsv.texi (8027B)
1 \input texinfo @c -*-texinfo-*- 2 3 @c %**start of header 4 @documentencoding UTF-8 5 @documentlanguage en 6 @setfilename guile-rsv.info 7 @settitle guile-rsv Reference Manual 8 @set VERSION 0.2.0 9 @set UPDATED 2024-01-22 10 @c %**end of header 11 12 @c XXX @include version.texi 13 14 @copying 15 Copyright @copyright{} 2024 Yuval Langer@* 16 17 Permission is granted to copy, distribute and/or modify this document 18 under the terms of the GNU Free Documentation License, Version 1.3 or 19 any later version published by the Free Software Foundation; with no 20 Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A 21 copy of the license is included in the section entitled ``GNU Free 22 Documentation License''. 23 @end copying 24 25 @dircategory The Algorithmic Language Scheme 26 @direntry 27 * guile-rsv: An R7RS compliant RSV (Rows of String Values) library. 28 @end direntry 29 30 @titlepage 31 @title guile-rsv Reference Manual 32 @subtitle Using guile-rsv 33 @author Yuval Langer and Zipheir 34 35 @page 36 @vskip 0pt plus 1filll 37 @c XXX Edition @value{EDITION} @* 38 @c XXX @value{UPDATED} @* 39 40 @insertcopying 41 @end titlepage 42 43 @contents 44 45 @node Top 46 @top guile-rsv 47 48 This document describes guile-rsv, a Rows of String Values (RSV) R7RS 49 compliant libraray (version @value{VERSION}, @value{UPDATED}). 50 51 @menu 52 * Introduction:: About guile-rsv. 53 * Installation:: Installing guile-rsv. 54 * Command-line Interface:: Using guile-rsv from the command-line. 55 * Programming Interface:: Reading and writing RSV in Scheme. 56 * Contributing:: How to contribute to guile-rsv. 57 * GNU Free Documentation License:: The license of this manual. 58 * Concept Index:: Concepts. 59 * Programming Index:: Data types, procedures, syntax, and variables. 60 @end menu 61 62 @node Introduction 63 @chapter Introduction 64 65 Rows of String Values is a data format used to represent a list of 66 list of unicode strings (or nulls), as shown in this BNF: 67 68 @verbatim 69 RSV := RSV-row* 70 RSV-Row := RSV-String-or-Null* Row-Terminator-Byte 71 RSV-String-or-Null := ( String | Null-Value-Byte ) Value-Terminator-Byte 72 String := a Unicode string encoded as UTF-8 73 Row-Terminator-Byte := 0xFD 74 Value-Terminator-Byte := 0xFF 75 Null-Value-Byte := 0xFE 76 @end verbatim 77 78 Contrary to CSV, TSV, and similar formats, which use commas, tabs, and 79 newlines, in RSV one can use UTF-8 string without modification thanks 80 to the fact that the byte values used to separate the fields are never 81 used by UTF-8. That is to say, we will never see 0xFD, 0xFF, or 0xFE 82 in a UTF-8 encoded Unicode. 83 84 More information on RSV's design can be found on: 85 86 The original specification repository written by Stefan John 87 (a.k.a. Stenway) @url{https://github.com/Stenway/RSV-Specification}, 88 and the video presentation 89 @url{https://www.youtube.com/watch?v=tb_70o6ohMA}. 90 91 @node Installation 92 @chapter Installation 93 94 @menu 95 * Downloading:: Downloading the source code. 96 * Guix Installation:: Installing from Guix. 97 * Requirements:: guile-rsv Requirements. 98 @end menu 99 100 @node Downloading 101 @section Downloading 102 103 Official guile-rsv source code is available from 104 @url{https://codeberg.org/kakafarm/guile-rsv, Codeberg}, 105 @url{https://git.sr.ht/~kakafarm/guile-rsv, Sourcehut}, or 106 @url{https://kaka.farm/~stagit/guile-rsv/log.html, Kaka Farm's 107 Stagit}. 108 109 @node Guix Installation 110 @section Guix Installation 111 112 Add the Guix Kaka Farm Channel from 113 @url{https://codeberg.org/kakafarm/guix-kakafarm-channel, codeberg}, 114 @url{https://git.sr.ht/~kakafarm/guix-kakafarm-channel/, Sourcehut}, 115 or @url{https://kaka.farm/~stagit/guix-kakafarm-channel.git/, Kaka 116 Farm's Repository} 117 (@url{https://kaka.farm/~stagit/guix-kakafarm-channel/log.html, Kaka 118 Farm's Stagit}) to your @code{~/.config/guix/channels.scm}. 119 120 Now: 121 122 @example 123 guix pull && guix install guile-rsv 124 @end example 125 126 @node Requirements 127 @section Requirements 128 129 guile-rsv depends on the following packages: 130 131 @itemize 132 @item 133 @url{https://gnu.org/software/guile, GNU Guile} 134 @item 135 @url{https://gnu.org/software/bash, GNU Bash} for the @command{rsv2scm} (@ref{Invoking rsv2scm}) and 136 @command{scm2rsv} (@ref{Invoking scm2rsv}) commands. 137 @end itemize 138 139 You can probably use other R7RS compatible Scheme implementations to 140 use the @code{(rsv)} and @code{(rsv rows-streams)} libraries. 141 142 @node Command-line Interface 143 @chapter Command-line Interface 144 145 @menu 146 * Invoking rsv2scm:: Convert RSV into lists of lists of strings. 147 * Invoking scm2rsv:: Convert Lists of lists of strings into RSV. 148 @end menu 149 150 rsv2scm reads binary RSV data from stdin and writes list of lists of 151 @var{string}-or-@var{#f} values into stdout. It may also produce a 152 list of @var{string}-or-@var{#f} values per line, each corresponding 153 to a row of RSV data. 154 155 scm2rsv does the opposite - it reads a list of lists of 156 @var{string}-or-@var{#f} from stdin and writes binary RSV data into 157 stdout. 158 159 @node Invoking rsv2scm 160 @section Invoking @command{rsv2scm} 161 162 Example: 163 164 @example 165 cat data.rsv | rsv2scm [-s/--stream] 166 @end example 167 168 @table @code 169 170 @item --stream 171 @itemx -s 172 Print one list of @var{string}-or-@var{#f} values per line. 173 174 @item --version 175 @itemx -V 176 Print version information. 177 178 @item --help 179 @itemx -h 180 Print an hopefully helpful help message. 181 182 @end table 183 184 @node Invoking scm2rsv 185 @section Invoking @command{scm2rsv} 186 187 Example: 188 189 @example 190 cat data.rsv | rsv2scm | scm2rsv > data-2.rsv 191 # Now data.rsv and data-2.rsv hold the same exact data. 192 @end example 193 194 @table @code 195 196 @item --version 197 @itemx -V 198 Print version information. 199 200 @item --help 201 @itemx -h 202 Print an hopefully helpful help message. 203 204 @end table 205 206 @node Programming Interface 207 @chapter Programming Interface 208 209 @menu 210 * Ports:: Read and write ports. 211 * Bytevectors:: Read and write bytevectors. 212 * Rows Streams:: Read ports as streams of RSV rows. 213 @end menu 214 215 You can read and write RSV using ports, bytevectors, or a stream 216 reading from a port. 217 218 @node Ports 219 @section Ports 220 221 @example 222 (import (rsv)) 223 @end example 224 225 @deffn {Procedure} read-rsv port 226 Read an RSV from PORT as a list of lists of string-or-null values. 227 228 @table @var 229 230 @item port 231 An input port from which an RSV is read. 232 233 @end table 234 235 @end deffn 236 237 @deffn {Procedure} write-rsv @var{scm} @var{port} 238 Write @var{scm} into an output port @var{port}. 239 240 @table @var 241 242 @item scm 243 A list of lists of string-or-null values. 244 245 @item port 246 An output port into which an RSV is written. 247 248 @end table 249 250 @end deffn 251 252 @node Bytevectors 253 @section Bytevectors 254 255 @example 256 (import (rsv)) 257 @end example 258 259 @deffn {Procedure} rsv-bytevector->scm @var{bv} 260 Convert bytevector @var{bv} holding the binary data of an RSV into a list 261 of lists of string-or-null values. 262 @end deffn 263 264 @deffn {Procedure} scm->rsv->bytevector @var{scm} 265 Convert @var{scm}, a list of lists of string-or-null values, into RSV 266 binary data held in a bytevector. 267 @end deffn 268 269 @node Rows Streams 270 @section Rows Streams 271 272 @example 273 (import (rsv rows-streams)) 274 @end example 275 276 @deffn {Procedure} port->rsv-row-stream @var{port} 277 Return a stream of lists of string-or-null values read from 278 @var{port}. 279 280 @end deffn 281 282 @node Contributing 283 @chapter Contributing 284 285 guile-rsv is developed using the Git version control system. The 286 official repository is hosted at 287 @url{https://kaka.farm/~stagit/guile-rsv.git}. 288 289 Tips, bug reports, suggestions, death threats, love letters, and 290 global (or local) conspiracy theories go to 291 @email{yuval.langer@@gmail.com}. You can also bug me on 292 @url{https://libera.chat/} where I go by @code{cow_2001} or on the 293 @url{https://matrix.org/} federation where I go by 294 @code{@@falconstinker:matrix.org} 295 296 @c ********************************************************************* 297 @node GNU Free Documentation License 298 @appendix GNU Free Documentation License 299 300 @include fdl-1.3.texi 301 302 @c ********************************************************************* 303 @node Concept Index 304 @unnumbered Concept Index 305 @printindex cp 306 307 @node Programming Index 308 @unnumbered Programming Index 309 @syncodeindex tp fn 310 @syncodeindex vr fn 311 @printindex fn 312 313 @bye 314 315 @c Local Variables: 316 @c ispell-local-dictionary: "american"; 317 @c End: