README.md

   1 # Factor
   2
   3 Factor is a [concatenative](https://www.concatenative.org), stack-based
   4 programming language with [high-level
   5 features](https://concatenative.org/wiki/view/Factor/Features/The%20language)
   6 including dynamic types, extensible syntax, macros, and garbage collection.
   7 On a practical side, Factor has a [full-featured
   8 library](https://docs.factorcode.org/content/article-vocab-index.html),
   9 supports many different platforms, and has been extensively documented.
  10
  11 The implementation is [fully
  12 compiled](https://concatenative.org/wiki/view/Factor/Optimizing%20compiler)
  13 for performance, while still supporting [interactive
  14 development](https://concatenative.org/wiki/view/Factor/Interactive%20development).
  15 Factor applications are portable between all common platforms.  Factor can
  16 [deploy stand-alone
  17 applications](https://concatenative.org/wiki/view/Factor/Deployment) on all
  18 platforms.  Full source code for the Factor project is available under a BSD
  19 license.
  20
  21 ## Getting Started
  22
  23 ### Building Factor from source
  24
  25 If you have a build environment set up, then you can build Factor from git.
  26 These scripts will attempt to compile the Factor binary and bootstrap from
  27 a boot image stored on factorcode.org.
  28
  29 To check out Factor:
  30
  31 * `git clone git://factorcode.org/git/factor.git`
  32 * `cd factor`
  33
  34 To build the latest complete Factor system from git:
  35
  36 * Windows: `build.cmd`
  37 * Unix: `./build.sh update`
  38
  39 Now you should have a complete Factor system ready to run.
  40
  41 More information on [building factor](https://concatenative.org/wiki/view/Factor/Building%20Factor)
  42 and [system requirements](https://concatenative.org/wiki/view/Factor/Requirements).
  43
  44 ### To run a Factor binary:
  45
  46 You can download a Factor binary from the grid on [https://factorcode.org](https://factorcode.org).
  47 The nightly builds are usually a better experience than the point releases.
  48
  49 * Windows: Double-click `factor.exe`, or run `.\factor.com` in a command prompt
  50 * Mac OS X: Double-click `Factor.app` or run `open Factor.app` in a Terminal
  51 * Unix: Run `./factor` in a shell
  52
  53 ### Learning Factor
  54
  55 A tutorial is available that can be accessed from the Factor environment:
  56
  57 ```factor
  58 "first-program" help
  59 ```
  60
  61 Some other simple things you can try in the listener:
  62
  63 ```factor
  64 "Hello, world" print
  65
  66 { 4 8 15 16 23 42 } [ 2 * ] map .
  67
  68 1000 [1,b] sum .
  69
  70 4 iota  [
  71     "Happy Birthday " write
  72     2 = "dear NAME" "to You" ? print
  73 ] each
  74 ```
  75
  76 For more tips, see [Learning Factor](https://concatenative.org/wiki/view/Factor/Learning).
  77
  78 ## Documentation
  79
  80 The Factor environment includes extensive reference documentation and a
  81 short "cookbook" to help you get started. The best way to read the
  82 documentation is in the UI; press F1 in the UI listener to open the help
  83 browser tool. You can also [browse the documentation
  84 online](https://docs.factorcode.org).
  85
  86 ## Command Line Usage
  87
  88 Factor supports a number of command line switches:
  89
  90 ```
  91 Usage: factor [Factor arguments] [script] [script arguments]
  92
  93 Common arguments:
  94     -help            print this message and exit
  95     -i=<image>       load Factor image file <image> (default factor.image)
  96     -run=<vocab>     run the MAIN: entry point of <vocab>
  97         -run=listener    run terminal listener
  98         -run=ui.tools    run Factor development UI
  99     -e=<code>        evaluate <code>
 100     -no-user-init    suppress loading of .factor-rc
 101     -roots=<paths>   a list of path-delimited extra vocab roots
 102
 103 Enter
 104     "command-line" help
 105 from within Factor for more information.
 106 ```
 107
 108 You can also write scripts that can be run from the terminal, by putting
 109 ``#!/path/to/factor`` at the top of your scripts and making them executable.
 110
 111 ## Source Organization
 112
 113 The Factor source tree is organized as follows:
 114
 115 * `vm/` - Factor VM source code (not present in binary packages)
 116 * `core/` - Factor core library
 117 * `basis/` - Factor basis library, compiler, tools
 118 * `extra/` - more libraries and applications
 119 * `misc/` - editor modes, icons, etc
 120 * `unmaintained/` - unmaintained contributions, please help!
 121
 122 ## Community
 123
 124 Factor developers meet in the `#concatenative` channel on
 125 [irc.freenode.net](http://freenode.net). Drop by if you want to discuss
 126 anything related to Factor or language design in general.
 127
 128 * [Factor homepage](https://factorcode.org)
 129 * [Concatenative languages wiki](https://concatenative.org)
 130
 131 Have fun!