www.aleph1.co.uk Git - yaffs-website/blob - node_modules/ini/README.md

   1 An ini format parser and serializer for node.
   2
   3 Sections are treated as nested objects.  Items before the first
   4 heading are saved on the object directly.
   5
   6 ## Usage
   7
   8 Consider an ini-file `config.ini` that looks like this:
   9
  10     ; this comment is being ignored
  11     scope = global
  12
  13     [database]
  14     user = dbuser
  15     password = dbpassword
  16     database = use_this_database
  17
  18     [paths.default]
  19     datadir = /var/lib/data
  20     array[] = first value
  21     array[] = second value
  22     array[] = third value
  23
  24 You can read, manipulate and write the ini-file like so:
  25
  26     var fs = require('fs')
  27       , ini = require('ini')
  28
  29     var config = ini.parse(fs.readFileSync('./config.ini', 'utf-8'))
  30
  31     config.scope = 'local'
  32     config.database.database = 'use_another_database'
  33     config.paths.default.tmpdir = '/tmp'
  34     delete config.paths.default.datadir
  35     config.paths.default.array.push('fourth value')
  36
  37     fs.writeFileSync('./config_modified.ini', ini.stringify(config, { section: 'section' }))
  38
  39 This will result in a file called `config_modified.ini` being written
  40 to the filesystem with the following content:
  41
  42     [section]
  43     scope=local
  44     [section.database]
  45     user=dbuser
  46     password=dbpassword
  47     database=use_another_database
  48     [section.paths.default]
  49     tmpdir=/tmp
  50     array[]=first value
  51     array[]=second value
  52     array[]=third value
  53     array[]=fourth value
  54
  55
  56 ## API
  57
  58 ### decode(inistring)
  59
  60 Decode the ini-style formatted `inistring` into a nested object.
  61
  62 ### parse(inistring)
  63
  64 Alias for `decode(inistring)`
  65
  66 ### encode(object, [options])
  67
  68 Encode the object `object` into an ini-style formatted string. If the
  69 optional parameter `section` is given, then all top-level properties
  70 of the object are put into this section and the `section`-string is
  71 prepended to all sub-sections, see the usage example above.
  72
  73 The `options` object may contain the following:
  74
  75 * `section` A string which will be the first `section` in the encoded
  76   ini data.  Defaults to none.
  77 * `whitespace` Boolean to specify whether to put whitespace around the
  78   `=` character.  By default, whitespace is omitted, to be friendly to
  79   some persnickety old parsers that don't tolerate it well.  But some
  80   find that it's more human-readable and pretty with the whitespace.
  81
  82 For backwards compatibility reasons, if a `string` options is passed
  83 in, then it is assumed to be the `section` value.
  84
  85 ### stringify(object, [options])
  86
  87 Alias for `encode(object, [options])`
  88
  89 ### safe(val)
  90
  91 Escapes the string `val` such that it is safe to be used as a key or
  92 value in an ini-file. Basically escapes quotes. For example
  93
  94     ini.safe('"unsafe string"')
  95
  96 would result in
  97
  98     "\"unsafe string\""
  99
 100 ### unsafe(val)
 101
 102 Unescapes the string `val`