Changeset 35525 in project


Ignore:
Timestamp:
05/06/18 17:49:44 (7 weeks ago)
Author:
felix
Message:

man/5: restructuring, fixed links, added csi module, simplification

Location:
wiki/man/5
Files:
3 added
5 deleted
9 edited
4 moved

Legend:

Unmodified
Added
Removed
  • wiki/man/5/Bugs and limitations

    r35318 r35525  
    2525
    2626---
    27 Previous: [[Extensions]]
     27Previous: [[Cross development]]
    2828
    2929Next: [[faq|FAQ]]
  • wiki/man/5/Cross development

    r35521 r35525  
    244244----
    245245Previous: [[Deployment]]
    246 Next: [[Supported language]]
     246Next: [[Bugs and limitation]]
  • wiki/man/5/Deviations from the standard

    r35520 r35525  
    9797
    9898---
    99 Previous: [[The R5RS standard]]
     99Previous: [[Using the compiler]]
    100100
    101101Next: [[Extensions to the standard]]
  • wiki/man/5/Extensions

    r35469 r35525  
    22[[toc:]]
    33
    4 == Eggs
     4== Introduction to extensions
    55
    66=== Extension libraries
     
    9494about the egg (author, license, dependencies etc).
    9595
    96 === Format of the egg description file
    97 
    98 An egg description is basically an association list holding
    99 information about the components of the egg. An egg may contain
    100 multiple components: libraries, programs, Scheme or C include files
    101 and arbitrary data files. Dependencies between eggs can be
    102 specified as can be dependencies between components of an egg.
    103 
    104 A list of valid properties follows.
    105 
    106 ==== Global properties
    107 
    108 ===== version
    109 
    110 [egg property] (version STRING)
    111 
    112 Specifies version string for this egg. {{STRING}} should have
    113 the format {{<MAJOR>.<MINOR>.<PATCHLEVEL>}}, where only the
    114 {{<MAJOR>}} part is mandatory.
    115 
    116 Eggs from remote egg servers are automatically versioned - the
    117 version is part of the protocol to retrieve the egg and does not
    118 have to be specified in the {{.egg}} file. Eggs installed from
    119 local directories (see below) should explicitly specify a version.
    120 
    121 ===== synopsis
    122 
    123 [egg property] (synopsis STRING)
    124 
    125 Gives a short description of this egg.
    126 
    127 ===== author
    128 
    129 [egg property] (author STRING)
    130 
    131 Names the author or authors of the contained code.
    132 
    133 ===== maintainer
    134 
    135 [egg property] (maintainer STRING)
    136 
    137 Names the maintainer of this code, if different from author(s).
    138 
    139 ===== category
    140 
    141 [egg property] (category NAME)
    142 
    143 Gives the category under which this egg should be contained.
    144 See [[/chicken-projects/egg-index-5.html|the egg index]]
    145 for a list of currently used categories.
    146 
    147 ===== license
    148 
    149 [egg property] (license STRING)
    150 
    151 Names the license under which this code is available.
    152 
    153 ===== dependencies
    154 
    155 [egg property] (dependencies EGG ...)
    156 
    157 Lists eggs that this egg depends on, and which should be
    158 built and installed if they do not already exist in the repository.
    159 {{EGG}} should be whether a symbol or a list of the form
    160 {{EGGNAME VERSION}}, where the former means to install the
    161 newest available egg with this name and the latter specifies
    162 a specific version or higher.
    163 
    164 Note that this property
    165 has a different meaning depending on whether it appears at
    166 toplevel in an egg description or inside a component.
    167 
    168 ====== test-dependencies
    169 
    170 [egg property] (test-dependencies EGG ...)
    171 
    172 Lists eggs that are required for this egg to run the tests
    173 (if tests exist.) This only has an effect if the {{-test}}
    174 option has been given to {{chicken-install}}.
    175 
    176 ====== build-dependencies
    177 
    178 [egg property] (build-dependencies EGG ...)
    179 
    180 Lists eggs that are build-time dependencies for this egg,
    181 i.e. there are required to build, but not to run the contained
    182 code. Currently this is treated identical to {{dependencies}}.
    183 
    184 ====== foreign-dependencies
    185 
    186 [egg property] (foreign-dependencies NAME ...)
    187 
    188 Lists external dependencies like native code libraries
    189 or system-specific packages and is currently only used for
    190 documentation purposes.
    191 
    192 ====== platform
    193 
    194 [egg property] (platform PLATFORM)
    195 
    196 Specifies for which platform this egg is intended. {{PLATFORM}}
    197 should be a symbol naming the target platform ({{windows}}, {{linux}}
    198 or {{unix}}) or a boolean combination of platform values, allowed
    199 are {{(not PLATFORM)}}, {{(or PLATFORM ...)}} and {{(and PLATFORM ...)}}.
    200 If the expression can not be satisfied, then installation of this
    201 egg will abort.
    202 
    203 ====== components
    204 
    205 [egg property] (components COMPONENT ...)
    206 
    207 Lists components (extensions, programs, include- or data files)
    208 that this extension installs. See below for information on how
    209 to specify component-specific information.
    210 
    211 ====== host
    212 
    213 [egg property] (host PROP ...)
    214 
    215 Recursively process {{PROP ...}}, but only for the host (build)
    216 platform, in case this is a "cross-chicken", a CHICKEN installation
    217 intended for cross compilation.
    218 
    219 ====== target
    220 
    221 [egg property] (target PROP ...)
    222 
    223 Recursively process {{PROP ...}}, but only for the target
    224 platform, in case this is a "cross-chicken", a CHICKEN installation
    225 intended for cross compilation.
    226 
    227 ===== Components
    228 
    229 ====== extension
    230 
    231 [egg property] (extension NAME PROP ...)
    232 
    233 Specifies an extension library component. The properties
    234 {{PROP...}} are processed recursively and apply only to this
    235 component.
    236 
    237 ====== data
    238 
    239 [egg property] (data NAME PROP ...)
    240 
    241 Specifies one or more arbitrary data files.
    242 
    243 ====== generated-source-file
    244 
    245 [egg property] (generated-source-file NAME PROP ...)
    246 
    247 Specifies a file that is generated during the process of building
    248 the egg.
    249 
    250 ====== c-include
    251 
    252 [egg property] (c-include NAME PROP ...)
    253 
    254 Specifies one or more C include files.
    255 
    256 ====== scheme-include
    257 
    258 [egg property] (scheme-include NAME PROP ...)
    259 
    260 Specifies one or more Scheme include files.
    261 
    262 ====== program
    263 
    264 [egg property] (program NAME PROP ...)
    265 
    266 Specifies an executable program.
    267 
    268 ===== Component properties
    269 
    270 ====== host
    271 
    272 [egg property] (host PROP ...)
    273 
    274 Process {{PROP ...}} recursively for the current component, but
    275 apply the properties only to the host (build) part, when using
    276 a CHICKEN installation intended for cross-compilation.
    277 
    278 ====== target
    279 
    280 [egg property] (target PROP ...)
    281 
    282 Process {{PROP ...}} recursively for the current component, but
    283 apply the properties only to the target part, when using
    284 a CHICKEN installation intended for cross-compilation.
    285 
    286 ====== linkage
    287 
    288 [egg property] (linkage LINKAGE)
    289 
    290 Define whether the component should be linked dynamically or
    291 statically. {{LINKAGE}} can be {{static}} or {{dynamic}}. This
    292 property only makes sense for extension libraries.
    293 
    294 ====== types-file
    295 
    296 [egg property] (types-file [NAME])
    297 
    298 Specifies that a "type-database" file should be generated and
    299 installed for this component. This property is only used for
    300 extension libraries. The name is optional and defaults to the
    301 name of the extensions (with the proper extension).
    302 
    303 If {{NAME}} is a list of the form {{(predefined [NAME])}}, then
    304 no types file is created during compilation and an existing types file
    305 for this extension is assumed and installed.
    306 
    307 ====== inline-file
    308 
    309 [egg property] (inline-file [NAME])
    310 
    311 Specifies that an "inline" file should be generated and installed
    312 for this component. This property is only used for extension
    313 libraries. The name is optional and defaults to the
    314 name of the extensions (with the proper extension).
    315 
    316 ====== custom-build
    317 
    318 [egg property] (custom-build STRING)
    319 
    320 Specifies a custom build operation that should be executed
    321 instead of the default build operations. This property is mandatory
    322 for components of type {{generated-source-file}}. {{STRING}}
    323 usually contains a shell command and thus may be platform sensitive.
    324 
    325 The script will be made executable on UNIX systems, if necessary,
    326 and will be invoked like the {{csc}} program and
    327 is executed with the location of the CHICKEN
    328 binaries in the {{PATH}}. Also, tjhe environment variables
    329 {{CHICKEN_CC}} and {{CHICKEN_CXX}} are set to the
    330 names of the C and C++ compiler that were used for building the
    331 system.
    332 
    333 ====== csc-options
    334 
    335 [egg property] (csc-options OPTION ...)
    336 
    337 Specifies additional compiler options for {{csc}} that should be
    338 used when building this component. If this property is not
    339 given, the default options are used, which are {{-O2 -d1}}
    340 for extensions and programs and {{-O2 -d0}} for import
    341 libraries.
    342 
    343 Note that the options are quoted when passed to csc during the
    344 compilation of the extension, so multiple options should be specified
    345 as {{(csc-options "OPT1" "OPT2" ...)}} instead of {{(csc-options "OPT1 OPT2")}}
    346 (the latter would be a single option containing a whitespace character).
    347 
    348 ====== link-options
    349 
    350 [egg property] (link-options OPTION ...)
    351 
    352 Specifies additional link options for {{csc}} that should be
    353 used when building this component.
    354 
    355 Note that the options are quoted when passed to csc during the
    356 compilation of the extension, so multiple options should be specified
    357 as {{(link-options "OPT1" "OPT2" ...)}} instead of {{(link-options "OPT1 OPT2")}}
    358 (the latter would be a single option containing a whitespace character).
    359 
    360 ====== source
    361 
    362 [egg property] (source NAME)
    363 
    364 Specifies an alternative source file, in case it has a name
    365 distinct from the component name. By default the source file
    366 for a component is named after the component, with the {{.scm}}
    367 extension added.
    368 
    369 ====== install-name
    370 
    371 [egg property] (install-name NAME)
    372 
    373 Specifies an alternative installation name of the component,
    374 if it differs from the actual component name. This property
    375 is most useful if an egg installs an extension and a program
    376 of the same name, but needs to distinguish the components during
    377 build time.
    378 
    379 ====== dependencies
    380 
    381 [egg property] (dependencies NAME ...)
    382 
    383 Specifies dependencies between components. Note that this use
    384 of the {{dependencies}} property is different from the property
    385 of the same name that is used at the "global" level of the
    386 egg description file.
    387 
    388 ====== destination
    389 
    390 [egg property] (destination NAME)
    391 
    392 Specifies an alternative installation destination for the
    393 built component and only applies
    394 to components of type {{data}}, {{c-include}} and {{scheme-include}}.
    395 This property should only be used in extreme
    396 cases, as it is recommended to use the default installation
    397 locations, which are:
    398 
    399 * for C include files: {{<PREFIX>/include/chicken/}}
    400 
    401 * for Scheme include files: {{<PREFIX>/share/chicken/}}
    402 
    403 * for data files: {{<PREFIX>/share/chicken/}}
    404 
    405 ====== files
    406 
    407 [egg property] (files NAME ...)
    408 
    409 Specifies source files for this component and only applies
    410 to components of type {{data}}, {{c-include}} and {{scheme-include}}.
    41196
    41297=== Examples for extensions
     
    571256 4
    572257
    573 ==== Notes on chicken-install
    574 
    575 When running {{chicken-install}} with an argument {{NAME}}, for which
    576 no associated {{.egg}} file exists, then it will try to download the
    577 extension via HTTP from the CHICKEN code repository at
    578 [[http://code.call-cc.org/svn/chicken-eggs/]]. Extensions that are
    579 required to compile and/or use the requested extension are downloaded
    580 and installed automatically.
    581 
    582258To query the list of currently installed extensions, use
    583259{{chicken-status}}. It can list what extensions are installed and
    584260what files belong to a particular installed extension.
    585261
    586 
    587 === chicken-install reference
    588 
    589 Available options:
    590 
    591 ; {{-h   -help}} : show this message and exit
    592 ; {{-version}} : show version and exit
    593 ; {{-force}} : don't ask, install even if versions don't match
    594 ; {{-k   -keep}} : keep temporary files
    595 ; {{-s   -sudo}} : use external command to elevate privileges when installing or removing files
    596 ; {{-no-install-deps}} : do not install dependencies
    597 ; {{-r   -retrieve}} : only retrieve egg into current directory, don't install (giving -r more than once implies {{-recursive}})
    598 ; {{-recursive}} : if {{-retrieve}} is given, retrieve also dependencies
    599 ; {{-dry-run}} :  do not build or install, just print the locations of the generated build + install scripts
    600 ; {{-list-versions}} : list available version for an extension (HTTP transport only)
    601 ; {{-n   -no-install}} : do not install, only build the egg.
    602 ; {{-purge}} : remove cached files for given eggs (or purge cache completely)
    603 ; {{-cached}} : install from cache, do not download
    604 ; {{-host}} : when cross-compiling, compile egg for host only
    605 ; {{-target}} : when cross-compiling, compile egg for target only
    606 ; {{-test}} : run included test-cases, if available
    607 ; {{-u   -update-db}} : update export database
    608 ; {{-repository}} : print path to egg repository
    609 ; {{-override FILENAME}} : override versions for installed eggs with information given in {{FILENAME}}, which can be generated by {{-scan}} or by the {{-list}} option of the {{chicken-status}} program
    610 : {{-from-list FILENAME}} : install eggs given in {{FILENAME}}, in the same format as produced by the {{-list}} option in {{chicken-status}}; this option may be given multiple times
    611 ; {{-v   -verbose}} : be verbose
    612 
    613 {{chicken-install}} recognizes the {{SUDO}}, {{http_proxy}} and {{proxy_auth}} environment variables, if set.
    614 
    615 
    616 === chicken-uninstall reference
    617 
    618 ; {{-h   -help}} : show usage information and exit
    619 ; {{-version}} : show version and exit
    620 ; {{-force}} : don't ask, delete whatever matches
    621 ; {{-match}} : treat egg-names as glob patterns
    622 ; {{-s   -sudo}} : use external command to elevate privileges for deleting files
    623 ; {{-host}} : when cross-compiling, remove eggs for host system only
    624 ; {{-target}} : when cross-compiling, remove eggs for target system only
    625 
    626 === chicken-status reference
    627 
    628 ; {{-h   -help}} : show usage information and exit
    629 ; {{-version}} : show version and exit
    630 ; {{-f   -files}} : list installed files
    631 ; {{-match}} : treat egg-names as glob patterns
    632 ; {{-host}} : when cross-compiling, show eggs for host system only
    633 ; {{-target}} : when cross-compiling, show eggs for target system only
    634 ; {{-list}} : list installed egg version in format suitable for {{chicken-install -override}} or {{-from-list}}
    635 ; {{-c   -components}} : list installed components
    636 ; {{-cached}} : list eggs available in the cache directory
    637 
    638 
    639 === Security
    640 
    641 When eggs are downloaded and installed one is executing code
    642 from potentially compromised systems. This applies also when
    643 {{chicken-install}} executes system tests for required eggs. As
    644 the code has been retrieved over the network effectively untrusted
    645 code is going to be evaluated. When {{chicken-install}} is run as
    646 ''root'' the whole system is at the mercy of the build instructions
    647 (note that this is also the case every time you install software via
    648 {{sudo make install}}, so this is not specific to the CHICKEN
    649 egg mechanism).
    650 
    651 Security-conscious users should never run {{chicken-install}} as root.
    652 A simple remedy is to keep the repository inside a user's home
    653 directory (see the section "Changing repository location" below).
    654 Alternatively obtain write/execute access to the default location of the repository
    655 (usually {{/usr/local/lib/chicken}}) to avoid running as
    656 root. {{chicken-install}} also provides a {{-sudo}} option to perform
    657 the last installation steps as root user, but do building and other
    658 .setup script processing as normal. A third solution is to
    659 override {{VARDIR}} when building the system
    660 (for example by passing {{"VARDIR=/foo/bar"}} on the make command line,
    661 or by modifying {{config.make}}. Eggs will then be installed in
    662 {{$(VARDIR)/chicken/8}}.
    663 
    664 === Changing the repository location
    665 
    666 When CHICKEN is installed a repository for eggs is created and initialized
    667 in a default location (usually something like {{/usr/local/lib/chicken/6/}}).
    668 It is possible to keep an egg repository in another location. This can be
    669 configured at build-time by passing {{VARDIR=<directory>}} to {{make(3)}}
    670 or by modifying the {{config.make}} configuration file. If you want to
    671 override this location after chicken is installed, you can create a
    672 repository directory, set the
    673 {{CHICKEN_INSTALL_REPOSITORY}} and/or {{CHICKEN_REPOSITORY_PATH}}
    674 environment variables and copy all files
    675 from the default repository into the new one.
    676 
    677 Note that your binary version can differ from the one given in
    678 the examples here, if your
    679 chicken version is older or newer than the one used in these examples.
    680 Check your default location for the correct binary-version number.
    681 
    682 {{CHICKEN_REPOSITORY_PATH}} is the place where eggs are to be
    683 loaded from for all chicken-based programs. {{CHICKEN_INSTALL_REPOSITORY}}
    684 is the place where eggs will be installed and which the egg-related
    685 tools like {{chicken-install}}, {{chicken-uninstall}} and
    686 {{chicken-status}} consult and update.
    687 
    688 
    689 === Static linking
    690 
    691 Static linking of extensions and programs is fully supported and
    692 should be transparent to the user. Every extension will by
    693 default be compiled into a dynamically loadable and a statically
    694 linkable entity. By passing {{-static}} on the {{csc}} command-line,
    695 eggs that are available in static form will be linked instead of
    696 the dynamically loadable version. Use the {{linkage}} egg
    697 description property to select in what modes a component should
    698 be built.
    699 
    700 To identify the necessary object files during linking of
    701 extensions, {{csc}}
    702 creates so-called "link files" and installs them along the
    703 statically compiled object file in the local egg repository.
    704 These link files specify what objects should be linked when
    705 an application is using a static variant of an extension.
    706 
    707 
    708 === Locations
    709 
    710 For experimentation or in-house builds of software it may be
    711 useful to have private egg repositories in addition to the
    712 official CHICKEN egg repository. This can be accomplished by
    713 defining so-called "locations", directories that contain egg
    714 source-code and description files and which should be scanned
    715 before trying to retrieve an egg via the network.
    716 
    717 The file {{<PREFIX>/share/chicken/setup.defaults}} holds various
    718 parameters that define where eggs should be downloaded, together
    719 with more obscure options, and can be used to customize the
    720 sources where eggs will be retrieved from. Adding a line of
    721 the form
    722 
    723 {{(location "<PATH>")}}
    724 
    725 will add {{<PATH>}} as an additional egg source, where {{<PATH>}}
    726 should be a directory in the local filesystem that contains
    727 any number of eggs, one directory for each, including the source code
    728 and the {{.egg}} files for each egg.
    729 
    730 Locations are searched before trying to retrieve from the network.
    731 Any number of locations may be defined.
    732 
    733 
    734 === The egg cache
    735 
    736 Eggs are downloaded and built in the so called "egg cache", an
    737 intermediate location used for storing already downloaded source code
    738 and for providing a temporary location for building the eggs before
    739 they are installed.
    740 
    741 By default the cache is located in the directory
    742 {{.chicken-install.cache}} is the user's home directory ({{$HOME}} on
    743 UNIX, or {{%USERPROFILE%}} on Windows. If the respective environment
    744 variable is not set, then {{/tmp}} or {{/Temp}} is used.
    745 
    746 Built extensions and programs remain in the cache, to avoid rebuilding
    747 already compiled code and multiple downloads of eggs in case the
    748 installation of an egg fails - the dependencies will be cached after
    749 the first download and re-download is not needed.
    750 
    751 {{chicken-install}} tries to take extreme care to avoid stale binaries,
    752 but should you be in doubt, simply delete the directory, or run
    753 {{chicken-install -purge}} to clear the cache or parts of it.
    754 
    755 You can override the location of the cache by setting the
    756 {{CHICKEN_EGG_CACHE}} environment variable.
    757 
    758 
    759 === Egg installation in detail
    760 
    761 ==== Retrieval
    762 
    763 First the egg names given on the command line (or, if no arguments
    764 are given, all eggs identified by {{.egg}} files in the current
    765 directory, including any in a subdirectory named {{chicken}})
    766 must be retrieved, either from a local source or from the official
    767 egg repository. Should the egg exist in the egg cache we check
    768 whether this cached version is out of date. A cached egg is
    769 considered out of date, if a) it is locally available and all cached
    770 files belonging to the egg do not have newer timestamps than the
    771 local files, or b) if it is a remotely retrieved egg and no
    772 newer versions exist on the remote egg server and the last time
    773 the cache was filled from the remote location is not later than
    774 one hour. Additionally, if any changes in certain environment
    775 variables that may influence the compilation of an egg, or if
    776 the CHICKEN version changed, then retrieval of the egg sources
    777 is enforced in any case.
    778 
    779 If the egg is in the current directory, or in
    780 a "location" (as described above), the files are copied into
    781 the cache. If the egg is remotely available, then it is retrieved
    782 via HTTP from one of the egg servers defined in {{setup.defaults}}.
    783 
    784 Once the egg sources are retrieved and stored in the cache,
    785 their {{.egg}} files are loaded and validated. After this
    786 any egg dependencies are resolved and located in the cache,
    787 triggering a recursive retrieval, if necessary.
    788 
    789 ==== Preparation
    790 
    791 Unless the {{-retrieve}} option was given, the eggs intended
    792 to be built and installed are now scheduled for compilation.
    793 The egg information from the {{.egg}} files is processed and
    794 translated into build and install scripts for the current
    795 platform - if this CHICKEN was configured for cross compilation,
    796 and no separate host- or target-build was selected, two sets
    797 of build/install scripts will be generated, one for the host
    798 system and one for the target.
    799 
    800 ==== Building and installation
    801 
    802 Unless {{-dry-run}} was given on the command-line, the build-
    803 and install scripts are now executed, ordered by the dependency
    804 relationships between the full set of eggs that are scheduled
    805 for compilation. If the {{-test}} option was given and a file named
    806 {{run.scm}} exists in the {{tests}} subdirectory of the egg
    807 sources, then this script is executed. Should it terminate with
    808 an error or a non-zero exit code, the installation is still performed
    809 and {{chicken-install}} does not abort. Only after all scheduled
    810 eggs have been installed, {{chicken-install}} will terminate
    811 with a non-zero exit code.
    812 
    813 Note that the build process attempts to minimize re-building
    814 of already compiled files in the cache, using the {{chicken-do}}
    815 program. See the manual page for {{chicken-do}} for more details.
    816 
    817 From the egg-information in the {{.egg}} file, the set of files
    818 installed for a particular egg are added to the egg-information
    819 and stored together with the build-artifacts produced by the
    820 build scripts.
     262For more information about the available tools and the various
     263options they provide, consult the [[Extension tools]] chapter.
     264
    821265
    822266---
    823267Previous: [[Interface to external functions and variables]]
    824268
    825 Next: [[Extensions]]
     269Next: [[Extension tools]]
  • wiki/man/5/Extensions to the standard

    r35520 r35525  
    5555The {{exit}} procedure exits a program right away and does ''not'' invoke pending {{dynamic-wind}} thunks.
    5656
     57
     58== Non-standard read syntax
     59
     60=== Escapes in symbols
     61
     62{{| ... |}} may be used to escape a sequence of characters when reading a symbol.
     63{{\X}} escapes a single character in a symbols name:
     64
     65  (symbol->string '|abc def|)       =>   "abc def"
     66  (symbol->string '|abc||def|)      =>   "abcdef"
     67  (symbol->string '|abc|xyz|def|)   =>   "abcxyzdef"
     68  (symbol->string '|abc\|def|)      =>   "abc|def"
     69  (symbol->string 'abc\ def)        =>   "abc def"
     70
     71=== Multiline Block Comment
     72
     73<read>#|</read>
     74
     75 #| ... |#
     76
     77A multiline ''block'' comment. May be nested. Implements [[http://srfi.schemers.org/srfi-30/srfi-30.html|SRFI-30]].
     78
     79=== Expression Comment
     80
     81<read>#;</read>
     82
     83 #;EXPRESSION
     84
     85Treats {{EXPRESSION}} as a comment.  That is, the comment runs through the whole S-expression, regardless of newlines, which saves you from having to comment out every line, or add a newline in the middle of your parens to make the commenting of the last line work, or other things like that. Implements [[http://srfi.schemers.org/srfi-62/srfi-62.html|SRFI-62]].
     86
     87=== External Representation
     88
     89<read>#,</read>
     90
     91 #,(CONSTRUCTORNAME DATUM ...)
     92
     93Allows user-defined extension of external representations. (For more information see the documentation for
     94[[http://srfi.schemers.org/srfi-10/srfi-10.html|SRFI-10]])
     95
     96=== Location Expression
     97
     98 #$EXPRESSION
     99
     100An abbreviation for {{(location EXPRESSION)}}.
     101
     102=== Blob literals
     103
     104<read>#${</read>
     105
     106  #${ HEX ... }
     107
     108Syntax for literal "blobs" (byte-sequences). Expects hexadecimal digits and ignores
     109any whitespace characters:
     110
     111  #;1> ,d '#${deadbee f}
     112  blob of size 4:
     113     0: de ad be ef                                     ....
     114
     115=== Keyword
     116
     117<read>#:</read>
     118
     119 #:SYMBOL
     120 SYMBOL:
     121 :SYMBOL
     122
     123Syntax for keywords. Keywords are symbols that evaluate to themselves, and as such don't have to be quoted.  Either {{SYMBOL:}} or {{:SYMBOL}} is accepted, depending on the setting of the {{keyword-style}} parameter, but never both.  {{#:SYMBOL}} is always accepted.
     124
     125=== Multiline String Constant
     126
     127<read>#<<</read>
     128
     129 #<<TAG
     130
     131Specifies a multiline string constant. Anything up to a line equal to {{TAG}} (or end of file) will be returned as a single string:
     132
     133 (define msg #<<END
     134  "Hello, world!", she said.
     135 END
     136 )
     137
     138is equivalent to
     139
     140 (define msg "\"Hello, world!\", she said.")
     141
     142=== Multiline String Constant with Embedded Expressions
     143
     144<read>#<#</read>
     145
     146 #<#TAG
     147
     148Similar to {{#<<}}, but allows substitution of embedded Scheme expressions prefixed with {{#}} and optionally enclosed in curly brackets. Two consecutive {{#}}s are translated to a single {{#}}:
     149
     150 (define three 3)
     151 (display #<#EOF
     152 This is a simple string with an embedded `##' character
     153 and substituted expressions: (+ three 99) ==> #(+ three 99)
     154 (three is "#{three}")
     155 EOF
     156 )
     157
     158prints
     159
     160 This is a simple string with an embedded `#' character
     161 and substituted expressions: (+ three 99) ==> 102
     162 (three is "3")
     163
     164=== Foreign Declare
     165
     166<read>#></read>
     167
     168 #> ... <#
     169
     170Abbreviation for {{(foreign-declare " ... ")}}.
     171
     172=== String escape sequences
     173
     174String-literals may contain the following escape sequences:
     175
     176<table style="margin-top: 1em; max-width: 40em">
     177<tr><th>Escape sequence</th><th>Character</th></tr>
     178<tr><td>{{\n}}</td><td>line feed / newline</td></tr>
     179<tr><td>{{\t}}</td><td>tab</td></tr>
     180<tr><td>{{\r}}</td><td>carriage return</td></tr>
     181<tr><td>{{\b}}</td><td>backspace</td></tr>
     182<tr><td>{{\a}}</td><td>bell</td></tr>
     183<tr><td>{{\v}}</td><td>vertical tab</td></tr>
     184<tr><td>{{\f}}</td><td>form feed</td></tr>
     185<tr><td>{{\x}}''XX''</td><td>hexadecimal 8-bit character code</td></tr>
     186<tr><td>{{\u}}''XXXX''</td><td>hexadecimal 16-bit Unicode character code</td></tr>
     187<tr><td>{{\U}}''XXXXXXXX''</td><td>hexadecimal 32-bit Unicode character code</td></tr>
     188<tr><td>{{\}}''OOO''</td><td>octal 8-bit character code</td></tr>
     189<tr><td>{{\|}}   {{\"}}    {{\\}}    {{\'}}</td><td>the escaped character</td></tr>
     190</table>
     191
     192
     193=== Sharp Prefixed Symbol
     194
     195<read>#%</read>
     196
     197 #%...
     198
     199Reads like a normal symbol.
     200
     201=== Bang
     202
     203<read>#!</read>
     204
     205 #!...
     206
     207Interpretation depends on the directly following characters. Only the following are recognized. Any other case results in a read error.
     208
     209; Line Comment : If followed by whitespace or a slash, then everything up the end of the current line is ignored
     210
     211; Eof Object : If followed by the character sequence {{eof}}, then the (self-evaluating) end-of-file object is returned
     212
     213; DSSSL Formal Parameter List Annotation : If followed by any of the character sequences {{optional}}, {{rest}} or {{key}}, then a symbol with the same name (and prefixed with {{#!}}) is returned
     214
     215; Read Mark Invocation : If a ''read mark'' with the same name as the token is registered, then its procedure is called and the result of the read-mark procedure will be returned
     216
     217=== Case Sensitive Expression
     218
     219<read>#cs</read>
     220
     221 #cs...
     222
     223Read the next expression in case-sensitive mode (regardless of the current global setting).
     224
     225=== Case Insensitive Expression
     226
     227<read>#ci</read>
     228
     229 #ci...
     230
     231Read the next expression in case-insensitive mode (regardless of the current global setting).
     232
     233=== Conditional Expansion
     234
     235<read>#+</read>
     236
     237 #+FEATURE EXPR
     238
     239Rewrites to
     240
     241 (cond-expand (FEATURE EXPR) (else))
     242
     243and performs the feature test at macroexpansion time.  Therefore, it may not
     244work as expected when used within a macro form.
     245
    57246---
    58247Previous: [[Deviations from the standard]]
    59248
    60 Next: [[Non-standard macros and special forms]]
     249Next: [[Included modules]]
  • wiki/man/5/Getting started

    r35324 r35525  
    545545Back to [[The User's Manual]]
    546546
    547 Next: [[Basic mode of operation]]
     547Next: [[Using the interpreter]]
  • wiki/man/5/Included modules

    r34992 r35525  
    1818* [[Module (chicken condition)]] : Raising and handling of exceptions, manipulation of condition objects
    1919* [[Module (chicken continuation)]] : Feeley's "a better API for continuations"
     20* [[Module (chicken csi)]] : Features specific to {{csi}}
    2021* [[Module (chicken errno)]] : Accessing the C "errno" variable
    2122* [[Module (chicken file)]] : High-level API for file system manipulations
     
    5354
    5455---
    55 Previous: [[Supported language]]
     56Previous: [[Extensions to the standard]]
    5657
    5758Next: [[Interface to external functions and variables]]
  • wiki/man/5/Interface to external functions and variables

    r35318 r35525  
    1818
    1919---
    20 Previous: [[Debugging]]
     20Previous: [[Included modules]]
    2121
    2222Next: [[Extensions]]
  • wiki/man/5/Module (chicken continuation)

    r34083 r35525  
    5959Previous: [[Module (chicken condition)]]
    6060
    61 Next: [[Module (chicken errno)]]
     61Next: [[Module (chicken csi)]]
  • wiki/man/5/The User's Manual

    r35522 r35525  
    1010
    1111* [[Getting started]] : What is CHICKEN and how do I use it?
    12 * [[User's Guide]] : A guide to the programs shipped with CHICKEN
    13 * [[Supported language]] : The language implemented by CHICKEN (deviations from the standard, limitations and extensions)
    14 * [[Interface to external functions and variables]] : Accessing C and C++ code and data.
     12* [[Using the interpreter]] : How to use the interactive interpreter, {{csi}}
     13* [[Using the compiler]]  : How to use the batch compiler
     14* [[Deviations from the standard]] : Where CHICKEN deviates from R5RS
     15* [[Extensions to the standard]] : Extensions to R5RS that CHICKEN provides
     16* [[Included modules]] : A reference to CHICKEN's core module library
     17* [[Interface to external functions and variables]] : Accessing C and C++ code and data
    1518* [[Extensions]] : Packaging and installing extension libraries
     19* [[Extension tools]] : {{chicken-[un]install}} and {{chicken-status}}
     20* [[Egg specification format]] : Format of egg description files
     21* [[Units and linking model]] : How Scheme compilations units are mapped to C
     22* [[Deployment]] : How to distribute and ship CHICKEN programs and libraries
     23* [[Cross development]] : Using CHICKEN to cross-compile for other architectures
    1624* [[Bugs and limitations]] : Things that do not work yet.
    17 * [[faq|FAQ]] : A list of Frequently Asked Questions about CHICKEN (and their answers).
    18 * [[Acknowledgements]] : A list of some of the people that have contributed to make CHICKEN what it is.
    19 * [[Bibliography]] : Links to documents that may be of interest.
     25* [[faq|FAQ]] : A list of Frequently Asked Questions about CHICKEN (and their answers)
     26* [[Acknowledgements]] : A list of some of the people that have contributed to make CHICKEN what it is
     27* [[Bibliography]] : Links to documents that may be of interest
  • wiki/man/5/Units and linking model

    r35472 r35525  
    7070
    7171----
    72 Previous: [[Using the compiler]]
     72Previous: [[Egg specification format]]
    7373Next: [[Deployment]]
  • wiki/man/5/Using the compiler

    r35522 r35525  
    479479Previous: [[Using the interpreter]]
    480480
    481 Next: [[Units and the linking model]]
     481Next: [[Deviations from the standard]]
  • wiki/man/5/Using the interpreter

    r35522 r35525  
    66CHICKEN provides an interpreter named {{csi}} for evaluating Scheme programs
    77and expressions interactively.
    8 
    9 === Interpreter command line format
    10 
    11 {{csi {FILENAME|OPTION}}}
    12 
    13 where {{FILENAME}} specifies a file with Scheme source-code.  If the
    14 extension of the source file is {{.scm}}, it may be omitted. The
    15 runtime options described in [[Using the compiler#Compiler command line format|Compiler command line format]] are also available
    16 for the interpreter.  If the environment variable {{CSI_OPTIONS}}
    17 is set to a list of options, then these options are additionally passed
    18 to every direct or indirect invocation of {{csi}}. Please note that
    19 runtime options (like {{-:...}}) can not be passed using this method.
    20 The options recognized by the interpreter are:
    21 
    22 ; -- : Ignore everything on the command-line following this marker. Runtime options ({{-:...}}) are still recognized.
    23 
    24 ; -i  -case-insensitive : Enables the reader to read symbols case insensitive. The default is to read case sensitive (in violation of R5RS).  This option registers the {{case-insensitive}} feature identifier.
    25 
    26 ; -b  -batch : Quit the interpreter after processing all command line options.
    27 
    28 ; -e  -eval EXPRESSIONS : Evaluate {{EXPRESSIONS}}. This option implies {{-batch}}, {{-no-init}} and {{-quiet}}, so no startup message will be printed and the interpreter exits after processing all {{-eval}} options and/or loading files given on the command-line.
    29 
    30 ; -p  -print EXPRESSIONS : Evaluate {{EXPRESSIONS}} and print the results of each expression using {{print}}. Implies {{-batch}}, {{-no-init}} and {{-quiet}}.
    31 
    32 ; -P  -pretty-print EXPRESSIONS : Evaluate {{EXPRESSIONS}} and print the results of each expression using {{pretty-print}}. Implies {{-batch}}, {{-no-init}} and {{-quiet}}.
    33 
    34 ; -D  -feature SYMBOL : Registers {{SYMBOL}} to be a valid feature identifier for {{cond-expand}} and {{feature?}}.
    35 
    36 ; -h  -help : Write a summary of the available command line options to standard output and exit.
    37 
    38 ; -I  -include-path PATHNAME : Specifies an alternative search-path for files included via the {{include}} special form. This option may be given multiple times. If the environment variable {{CHICKEN_INCLUDE_PATH}} is set, it should contain a list of alternative include pathnames separated by {{;}}.
    39 
    40 ; -K  -keyword-style STYLE : Enables alternative keyword syntax, where {{STYLE}} may be either {{prefix}} (as in Common Lisp) or {{suffix}} (as in DSSSL). Any other value is ignored.
    41 
    42 ; -n  -no-init : Do not load initialization-file. If this option is not given and the file {{$HOME/.csirc}} exists, then it is loaded before the read-eval-print loop commences.
    43 
    44 ;     -no-parentheses-synonyms : Disables list delimiter synonyms, [..] and {...} for (...).
    45 
    46 ;     -no-symbol-escape : Disables support for escaped symbols, the |...| form.
    47 
    48 ; -w  -no-warnings : Disables any warnings that might be issued by the reader or evaluated code.
    49 
    50 ; -q  -quiet : Do not print a startup message. Also disables generation of call-trace information for interpreted code.
    51 
    52 ;     -r5rs-syntax : Disables the CHICKEN extensions to R5RS syntax. Does not disable [[Non-standard read syntax|non-standard read syntax]].
    53 
    54 ; -s  -script PATHNAME : This is equivalent to {{-batch -quiet -no-init PATHNAME}}. Arguments following {{PATHNAME}} are available by using  {{command-line-arguments}} and are not processed as interpreter options. Extra options in the environment variable {{CSI_OPTIONS}} are ignored.
    55 
    56 ; -sx PATHNAME : The same as {{-s PATHNAME}} but prints each expression to {{(current-error-port)}} before it is evaluated.
    57 
    58 ; -ss PATHNAME : The same as {{-s PATHNAME}} but invokes the procedure {{main}} with the value of {{(command-line-arguments)}} as its single argument. If the main procedure returns an integer result, then the interpreter is terminated, returning the integer as the status code back to the invoking process. Any other result terminates the interpreter with a zero exit status.
    59 
    60 ; -setup-mode : When locating extensions, search the current directory first. By default, extensions are located first in the ''extension repository'', where {{chicken-install}} stores compiled extensions and their associated metadata.
    61 
    62 ; -R  -require-extension NAME : Equivalent to evaluating {{(require-extension NAME)}}.
    63 
    64 ; -v  -version : Write the banner with version information to standard output and exit.
    65 
    668
    679=== Writing Scheme scripts
     
    193135
    194136
    195 === toplevel-command
    196 
    197 <procedure>(toplevel-command SYMBOL PROC [HELPSTRING])</procedure>
    198 
    199 Defines or redefines a toplevel interpreter command which can be invoked by entering
    200 {{,SYMBOL}}. {{PROC}} will be invoked when the command is entered and may
    201 read any required argument via {{read}} (or {{read-line}}). If the optional
    202 argument {{HELPSTRING}} is given, it will be listed by the {{,?}} command.
    203 
    204 This procedure is provided by the {{(chicken csi)}} module.
    205 
    206 
    207137=== Getting error information
    208138
     
    246176The {{,e}} command runs the editor given by:
    247177
    248 * The parameter {{editor-command}} which should return a string naming
     178* The parameter {{editor-command}} in the {{(chicken csi)}} module should
     179  return a string naming
    249180  an external editor and defaults to {{#f}}, which means no editor is currently
    250181  selected (so the following alternatives are tried).
     
    254185* If the environment variable {{EMACS}} is set, the editor chosen is {{emacsclient}}.
    255186
    256 * As a truly last resort, {{vi}} is used.
     187* In a desparate attempt to find an editor, {{vi}} is used.
    257188
    258189=== History access
     
    265196character follows the {{#}}, then the result of the last expression is
    266197returned.  Note that the value returned is implicitly quoted.
    267 
    268 === set-describer!
    269 
    270 <procedure>(set-describer! TAG PROC)</procedure>
    271 
    272 Sets a custom description handler that invokes {{PROC}} when the
    273 {{,d}} command is invoked with a record-type object that has the type
    274 {{TAG}} (a symbol). {{PROC}} is called with two arguments: the object
    275 to be described and an output-port. It should write a possibly useful
    276 textual description of the object to the passed output-port. For
    277 example:
    278 
    279  #;1> (define-record-type point (make-point x y) point?
    280         (x point-x)
    281         (y point-y))
    282  #;2> (set-describer! 'point
    283         (lambda (pt o)
    284           (with-output-to-port o
    285             (lambda ()
    286               (print "a point with x=" (point-x pt) " and y=" (point-y pt))))))
    287  #;3> ,d (make-point 1 2)
    288  a point with x=1 and y=2
    289 
    290 This procedure is provided by the {{(chicken csi)}} module.
    291 
    292198
    293199=== Auto-completion and edition
     
    305211auto-completion).
    306212
     213
     214=== csi command line format
     215
     216{{csi {FILENAME|OPTION}}}
     217
     218where {{FILENAME}} specifies a file with Scheme source-code.  If the
     219extension of the source file is {{.scm}}, it may be omitted. The
     220runtime options described in [[Using the compiler#Compiler command line format|Compiler command line format]] are also available
     221for the interpreter.  If the environment variable {{CSI_OPTIONS}}
     222is set to a list of options, then these options are additionally passed
     223to every direct or indirect invocation of {{csi}}. Please note that
     224runtime options (like {{-:...}}) can not be passed using this method.
     225The options recognized by the interpreter are:
     226
     227; -- : Ignore everything on the command-line following this marker. Runtime options ({{-:...}}) are still recognized.
     228
     229; -i  -case-insensitive : Enables the reader to read symbols case insensitive. The default is to read case sensitive (in violation of R5RS).  This option registers the {{case-insensitive}} feature identifier.
     230
     231; -b  -batch : Quit the interpreter after processing all command line options.
     232
     233; -e  -eval EXPRESSIONS : Evaluate {{EXPRESSIONS}}. This option implies {{-batch}}, {{-no-init}} and {{-quiet}}, so no startup message will be printed and the interpreter exits after processing all {{-eval}} options and/or loading files given on the command-line.
     234
     235; -p  -print EXPRESSIONS : Evaluate {{EXPRESSIONS}} and print the results of each expression using {{print}}. Implies {{-batch}}, {{-no-init}} and {{-quiet}}.
     236
     237; -P  -pretty-print EXPRESSIONS : Evaluate {{EXPRESSIONS}} and print the results of each expression using {{pretty-print}}. Implies {{-batch}}, {{-no-init}} and {{-quiet}}.
     238
     239; -D  -feature SYMBOL : Registers {{SYMBOL}} to be a valid feature identifier for {{cond-expand}} and {{feature?}}.
     240
     241; -h  -help : Write a summary of the available command line options to standard output and exit.
     242
     243; -I  -include-path PATHNAME : Specifies an alternative search-path for files included via the {{include}} special form. This option may be given multiple times. If the environment variable {{CHICKEN_INCLUDE_PATH}} is set, it should contain a list of alternative include pathnames separated by {{;}}.
     244
     245; -K  -keyword-style STYLE : Enables alternative keyword syntax, where {{STYLE}} may be either {{prefix}} (as in Common Lisp) or {{suffix}} (as in DSSSL). Any other value is ignored.
     246
     247; -n  -no-init : Do not load initialization-file. If this option is not given and the file {{$HOME/.csirc}} exists, then it is loaded before the read-eval-print loop commences.
     248
     249;     -no-parentheses-synonyms : Disables list delimiter synonyms, [..] and {...} for (...).
     250
     251;     -no-symbol-escape : Disables support for escaped symbols, the |...| form.
     252
     253; -w  -no-warnings : Disables any warnings that might be issued by the reader or evaluated code.
     254
     255; -q  -quiet : Do not print a startup message. Also disables generation of call-trace information for interpreted code.
     256
     257;     -r5rs-syntax : Disables the CHICKEN extensions to R5RS syntax. Does not disable [[Non-standard read syntax|non-standard read syntax]].
     258
     259; -s  -script PATHNAME : This is equivalent to {{-batch -quiet -no-init PATHNAME}}. Arguments following {{PATHNAME}} are available by using  {{command-line-arguments}} and are not processed as interpreter options. Extra options in the environment variable {{CSI_OPTIONS}} are ignored.
     260
     261; -sx PATHNAME : The same as {{-s PATHNAME}} but prints each expression to {{(current-error-port)}} before it is evaluated.
     262
     263; -ss PATHNAME : The same as {{-s PATHNAME}} but invokes the procedure {{main}} with the value of {{(command-line-arguments)}} as its single argument. If the main procedure returns an integer result, then the interpreter is terminated, returning the integer as the status code back to the invoking process. Any other result terminates the interpreter with a zero exit status.
     264
     265; -setup-mode : When locating extensions, search the current directory first. By default, extensions are located first in the ''extension repository'', where {{chicken-install}} stores compiled extensions and their associated metadata.
     266
     267; -R  -require-extension NAME : Equivalent to evaluating {{(require-extension NAME)}}.
     268
     269; -v  -version : Write the banner with version information to standard output and exit.
     270
     271
    307272---
    308 Previous: [[Overview]]
     273Previous: [[Getting started]]
    309274
    310275Next: [[Using the compiler]]
Note: See TracChangeset for help on using the changeset viewer.