# FCLPY - A Common Lisp Interpreter in Python
FCLPY is a Common Lisp interpreter implemented in Python. It provides a complete Lisp environment with an interactive REPL, file evaluation, and a clean API for embedding Lisp functionality into Python applications.
## Features
### 🚀 **Complete Lisp Implementation**
- **Arithmetic Operations**: `+`, `-`, `*`, `/`, `=`, `<`, `>`, `<=`, `>=`
- **List Operations**: `car`, `cdr`, `cons`, `list`, `append`, `reverse`
- **Logic Functions**: `not`, `and`, `or`
- **Predicates**: `atom`, `null`, `eq`, `equal`, `symbolp`, `numberp`, `stringp`
- **Special Forms**: `quote`, `if`, `setq`, `let`, `defun`, `lambda`
### 💻 **Interactive REPL**
- Command-line interface similar to CLISP
- Interactive Read-Eval-Print Loop
- Built-in help system and debugging commands
- Support for multi-line expressions
### 📁 **File Evaluation**
- Load and evaluate Lisp files
- Silent loading (standard Lisp behavior)
- Verbose mode for debugging
- Proper error handling and reporting
### 🔧 **Python Integration**
- Clean API for embedding in Python projects
- Programmatic REPL control
- Function evaluation from Python
- Environment management
## Installation
### From Source
```bash
git clone https://github.com/fclpy/fclpy.git
cd fclpy
pip install -e .
```
### Using Pipenv (Development)
```bash
git clone https://github.com/fclpy/fclpy.git
cd fclpy
pipenv install
pipenv shell
```
## Quick Start
### Command Line Usage
#### Start Interactive REPL
```bash
fclpy
```
#### Run a Lisp File
```bash
fclpy script.lisp
```
#### Run with Verbose Output
```bash
fclpy -v script.lisp
```
#### Run Tests
```bash
fclpy --test
```
### Example Lisp Session
```lisp
FCLPY> (+ 1 2 3)
6
FCLPY> (defun square (x) (* x x))
SQUARE
FCLPY> (square 5)
25
FCLPY> (car '(a b c))
A
FCLPY> (cons 'first '(second third))
(FIRST SECOND THIRD)
```
## Python API
### Basic Usage
```python
from fclpy import runtime, lispenv
# Initialize Lisp environment
lispenv.setup_standard_environment()
# Start interactive REPL
runtime.repl()
```
### Load and Evaluate Files
```python
from fclpy import runtime, lispenv
# Set up environment
lispenv.setup_standard_environment()
env = lispenv.current_environment
# Load a Lisp file
success = runtime.load_and_evaluate_file("my_script.lisp", env)
```
### Custom REPL
```python
from fclpy.runtime import FclpyREPL
# Create custom REPL
repl = FclpyREPL(quiet=True, verbose=False)
repl.run()
```
## Language Support
### Data Types
- **Numbers**: Integers and floating-point
- **Strings**: Double-quoted strings with escape sequences
- **Symbols**: Case-insensitive identifiers
- **Lists**: Linked lists using cons cells
- **Booleans**: `T` (true) and `NIL` (false/empty list)
### Special Forms
```lisp
;; Variable assignment
(setq x 42)
;; Conditional expressions
(if (> x 0) 'positive 'negative)
;; Function definition
(defun factorial (n)
(if (<= n 1)
1
(* n (factorial (- n 1)))))
;; Local bindings
(let ((x 10) (y 20))
(+ x y))
;; Lambda expressions
((lambda (x) (* x x)) 5)
```
### Built-in Functions
```lisp
;; Arithmetic
(+ 1 2 3 4) ; => 10
(* 2 3 4) ; => 24
(- 10 3) ; => 7
(/ 15 3) ; => 5
;; Comparisons
(= 5 5) ; => T
(< 3 7) ; => T
(<= 5 5) ; => T
;; List operations
(cons 1 '(2 3)) ; => (1 2 3)
(car '(a b c)) ; => A
(cdr '(a b c)) ; => (B C)
(list 1 2 3) ; => (1 2 3)
;; Predicates
(atom 'x) ; => T
(null '()) ; => T
(symbolp 'hello) ; => T
(numberp 42) ; => T
```
## Command Line Options
FCLPY supports many CLISP-compatible command-line options:
```bash
fclpy [options] [files...]
Options:
-h, --help Show help message
-i, --interactive Enter REPL after processing files
-q, --quiet Suppress startup messages
-v, --verbose Verbose output
--test Run comprehensive tests
--version Show version number
-E ENCODING File encoding (default: utf-8)
-norc Do not load init file
-ansi ANSI Common Lisp mode
```
## Examples
### Example 1: Simple Calculator
```lisp
;; calculator.lisp
(defun add (a b) (+ a b))
(defun multiply (a b) (* a b))
(defun square (x) (* x x))
(square (add 3 4)) ; => 49
```
### Example 2: List Processing
```lisp
;; lists.lisp
(defun length (lst)
(if (null lst)
0
(+ 1 (length (cdr lst)))))
(defun reverse-list (lst)
(if (null lst)
'()
(append (reverse-list (cdr lst)) (list (car lst)))))
(length '(a b c d)) ; => 4
(reverse-list '(1 2 3)) ; => (3 2 1)
```
### Example 3: Recursive Functions
```lisp
;; recursion.lisp
(defun factorial (n)
(if (<= n 1)
1
(* n (factorial (- n 1)))))
(defun fibonacci (n)
(if (<= n 2)
1
(+ (fibonacci (- n 1)) (fibonacci (- n 2)))))
(factorial 5) ; => 120
(fibonacci 7) ; => 13
```
## Testing
FCLPY includes a comprehensive test suite with 54 tests covering all major functionality:
```bash
# Run all tests
fclpy --test
# Run tests with verbose output
fclpy -v --test
```
Test categories:
- Function name mapping
- Arithmetic operations
- Basic evaluation
- Special forms
- Environment management
- Metacircular readiness
## Development
### Project Structure
```
fclpy/
├── fclpy/ # Core interpreter package
│ ├── __init__.py # Package initialization
│ ├── runtime.py # Main runtime and REPL
│ ├── lispenv.py # Environment management
│ ├── lispfunc.py # Function implementations
│ ├── lispreader.py # S-expression reader
│ └── lisptype.py # Data type definitions
├── run.py # CLI entry point
├── test_comprehensive.py # Test suite
├── setup.py # Package setup
└── README.md # This file
```
### Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run the test suite: `fclpy --test`
5. Submit a pull request
### Running Tests
```bash
# Run comprehensive test suite
python run.py --test
# Run with verbose output
python run.py -v --test
```
## License
MIT License - see LICENSE file for details.
## Compatibility
- **Python**: 3.7+
- **Operating Systems**: Windows, macOS, Linux
- **Dependencies**: None (pure Python implementation)
## Roadmap
### Current Status ✅
- [x] Complete Lisp interpreter
- [x] Interactive REPL
- [x] File evaluation
- [x] Comprehensive test suite
- [x] Python API
- [x] CLI interface
### Future Enhancements 🚧
- [ ] Macro system
- [ ] Package system
- [ ] Error handling improvements
- [ ] Performance optimizations
- [ ] Additional built-in functions
- [ ] Documentation improvements
## Examples and Learning
FCLPY is perfect for:
- Learning Lisp programming
- Teaching interpreter implementation
- Embedding Lisp in Python applications
- Rapid prototyping of symbolic computation
- Educational projects
## Support
- **Issues**: [GitHub Issues](https://github.com/fclpy/fclpy/issues)
- **Documentation**: [Wiki](https://github.com/fclpy/fclpy/wiki)
- **Source**: [GitHub Repository](https://github.com/fclpy/fclpy)
---
**FCLPY** - Bringing the power of Lisp to Python! 🚀
Raw data
{
"_id": null,
"home_page": "https://github.com/your-username/fclpy",
"name": "fclpy",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "lisp, interpreter, common-lisp, programming-language, repl",
"author": "FCLPY Development Team",
"author_email": "fclpy@example.com",
"download_url": "https://files.pythonhosted.org/packages/19/35/122b02cab89960dd6db4adcf46ac191341800c56fb2bf62d0eb5cbd95f79/fclpy-0.1.0.tar.gz",
"platform": "any",
"description": "# FCLPY - A Common Lisp Interpreter in Python\r\n\r\n\r\n\r\n\r\n\r\nFCLPY is a Common Lisp interpreter implemented in Python. It provides a complete Lisp environment with an interactive REPL, file evaluation, and a clean API for embedding Lisp functionality into Python applications.\r\n\r\n## Features\r\n\r\n### \ud83d\ude80 **Complete Lisp Implementation**\r\n- **Arithmetic Operations**: `+`, `-`, `*`, `/`, `=`, `<`, `>`, `<=`, `>=`\r\n- **List Operations**: `car`, `cdr`, `cons`, `list`, `append`, `reverse`\r\n- **Logic Functions**: `not`, `and`, `or`\r\n- **Predicates**: `atom`, `null`, `eq`, `equal`, `symbolp`, `numberp`, `stringp`\r\n- **Special Forms**: `quote`, `if`, `setq`, `let`, `defun`, `lambda`\r\n\r\n### \ud83d\udcbb **Interactive REPL**\r\n- Command-line interface similar to CLISP\r\n- Interactive Read-Eval-Print Loop\r\n- Built-in help system and debugging commands\r\n- Support for multi-line expressions\r\n\r\n### \ud83d\udcc1 **File Evaluation**\r\n- Load and evaluate Lisp files\r\n- Silent loading (standard Lisp behavior)\r\n- Verbose mode for debugging\r\n- Proper error handling and reporting\r\n\r\n### \ud83d\udd27 **Python Integration**\r\n- Clean API for embedding in Python projects\r\n- Programmatic REPL control\r\n- Function evaluation from Python\r\n- Environment management\r\n\r\n## Installation\r\n\r\n### From Source\r\n```bash\r\ngit clone https://github.com/fclpy/fclpy.git\r\ncd fclpy\r\npip install -e .\r\n```\r\n\r\n### Using Pipenv (Development)\r\n```bash\r\ngit clone https://github.com/fclpy/fclpy.git\r\ncd fclpy\r\npipenv install\r\npipenv shell\r\n```\r\n\r\n## Quick Start\r\n\r\n### Command Line Usage\r\n\r\n#### Start Interactive REPL\r\n```bash\r\nfclpy\r\n```\r\n\r\n#### Run a Lisp File\r\n```bash\r\nfclpy script.lisp\r\n```\r\n\r\n#### Run with Verbose Output\r\n```bash\r\nfclpy -v script.lisp\r\n```\r\n\r\n#### Run Tests\r\n```bash\r\nfclpy --test\r\n```\r\n\r\n### Example Lisp Session\r\n```lisp\r\nFCLPY> (+ 1 2 3)\r\n6\r\nFCLPY> (defun square (x) (* x x))\r\nSQUARE\r\nFCLPY> (square 5)\r\n25\r\nFCLPY> (car '(a b c))\r\nA\r\nFCLPY> (cons 'first '(second third))\r\n(FIRST SECOND THIRD)\r\n```\r\n\r\n## Python API\r\n\r\n### Basic Usage\r\n```python\r\nfrom fclpy import runtime, lispenv\r\n\r\n# Initialize Lisp environment\r\nlispenv.setup_standard_environment()\r\n\r\n# Start interactive REPL\r\nruntime.repl()\r\n```\r\n\r\n### Load and Evaluate Files\r\n```python\r\nfrom fclpy import runtime, lispenv\r\n\r\n# Set up environment\r\nlispenv.setup_standard_environment()\r\nenv = lispenv.current_environment\r\n\r\n# Load a Lisp file\r\nsuccess = runtime.load_and_evaluate_file(\"my_script.lisp\", env)\r\n```\r\n\r\n### Custom REPL\r\n```python\r\nfrom fclpy.runtime import FclpyREPL\r\n\r\n# Create custom REPL\r\nrepl = FclpyREPL(quiet=True, verbose=False)\r\nrepl.run()\r\n```\r\n\r\n## Language Support\r\n\r\n### Data Types\r\n- **Numbers**: Integers and floating-point\r\n- **Strings**: Double-quoted strings with escape sequences\r\n- **Symbols**: Case-insensitive identifiers\r\n- **Lists**: Linked lists using cons cells\r\n- **Booleans**: `T` (true) and `NIL` (false/empty list)\r\n\r\n### Special Forms\r\n```lisp\r\n;; Variable assignment\r\n(setq x 42)\r\n\r\n;; Conditional expressions\r\n(if (> x 0) 'positive 'negative)\r\n\r\n;; Function definition\r\n(defun factorial (n)\r\n (if (<= n 1)\r\n 1\r\n (* n (factorial (- n 1)))))\r\n\r\n;; Local bindings\r\n(let ((x 10) (y 20))\r\n (+ x y))\r\n\r\n;; Lambda expressions\r\n((lambda (x) (* x x)) 5)\r\n```\r\n\r\n### Built-in Functions\r\n```lisp\r\n;; Arithmetic\r\n(+ 1 2 3 4) ; => 10\r\n(* 2 3 4) ; => 24\r\n(- 10 3) ; => 7\r\n(/ 15 3) ; => 5\r\n\r\n;; Comparisons\r\n(= 5 5) ; => T\r\n(< 3 7) ; => T\r\n(<= 5 5) ; => T\r\n\r\n;; List operations\r\n(cons 1 '(2 3)) ; => (1 2 3)\r\n(car '(a b c)) ; => A\r\n(cdr '(a b c)) ; => (B C)\r\n(list 1 2 3) ; => (1 2 3)\r\n\r\n;; Predicates\r\n(atom 'x) ; => T\r\n(null '()) ; => T\r\n(symbolp 'hello) ; => T\r\n(numberp 42) ; => T\r\n```\r\n\r\n## Command Line Options\r\n\r\nFCLPY supports many CLISP-compatible command-line options:\r\n\r\n```bash\r\nfclpy [options] [files...]\r\n\r\nOptions:\r\n -h, --help Show help message\r\n -i, --interactive Enter REPL after processing files\r\n -q, --quiet Suppress startup messages\r\n -v, --verbose Verbose output\r\n --test Run comprehensive tests\r\n --version Show version number\r\n -E ENCODING File encoding (default: utf-8)\r\n -norc Do not load init file\r\n -ansi ANSI Common Lisp mode\r\n```\r\n\r\n## Examples\r\n\r\n### Example 1: Simple Calculator\r\n```lisp\r\n;; calculator.lisp\r\n(defun add (a b) (+ a b))\r\n(defun multiply (a b) (* a b))\r\n(defun square (x) (* x x))\r\n\r\n(square (add 3 4)) ; => 49\r\n```\r\n\r\n### Example 2: List Processing\r\n```lisp\r\n;; lists.lisp\r\n(defun length (lst)\r\n (if (null lst)\r\n 0\r\n (+ 1 (length (cdr lst)))))\r\n\r\n(defun reverse-list (lst)\r\n (if (null lst)\r\n '()\r\n (append (reverse-list (cdr lst)) (list (car lst)))))\r\n\r\n(length '(a b c d)) ; => 4\r\n(reverse-list '(1 2 3)) ; => (3 2 1)\r\n```\r\n\r\n### Example 3: Recursive Functions\r\n```lisp\r\n;; recursion.lisp\r\n(defun factorial (n)\r\n (if (<= n 1)\r\n 1\r\n (* n (factorial (- n 1)))))\r\n\r\n(defun fibonacci (n)\r\n (if (<= n 2)\r\n 1\r\n (+ (fibonacci (- n 1)) (fibonacci (- n 2)))))\r\n\r\n(factorial 5) ; => 120\r\n(fibonacci 7) ; => 13\r\n```\r\n\r\n## Testing\r\n\r\nFCLPY includes a comprehensive test suite with 54 tests covering all major functionality:\r\n\r\n```bash\r\n# Run all tests\r\nfclpy --test\r\n\r\n# Run tests with verbose output\r\nfclpy -v --test\r\n```\r\n\r\nTest categories:\r\n- Function name mapping\r\n- Arithmetic operations\r\n- Basic evaluation\r\n- Special forms\r\n- Environment management\r\n- Metacircular readiness\r\n\r\n## Development\r\n\r\n### Project Structure\r\n```\r\nfclpy/\r\n\u251c\u2500\u2500 fclpy/ # Core interpreter package\r\n\u2502 \u251c\u2500\u2500 __init__.py # Package initialization\r\n\u2502 \u251c\u2500\u2500 runtime.py # Main runtime and REPL\r\n\u2502 \u251c\u2500\u2500 lispenv.py # Environment management\r\n\u2502 \u251c\u2500\u2500 lispfunc.py # Function implementations\r\n\u2502 \u251c\u2500\u2500 lispreader.py # S-expression reader\r\n\u2502 \u2514\u2500\u2500 lisptype.py # Data type definitions\r\n\u251c\u2500\u2500 run.py # CLI entry point\r\n\u251c\u2500\u2500 test_comprehensive.py # Test suite\r\n\u251c\u2500\u2500 setup.py # Package setup\r\n\u2514\u2500\u2500 README.md # This file\r\n```\r\n\r\n### Contributing\r\n\r\n1. Fork the repository\r\n2. Create a feature branch\r\n3. Make your changes\r\n4. Run the test suite: `fclpy --test`\r\n5. Submit a pull request\r\n\r\n### Running Tests\r\n```bash\r\n# Run comprehensive test suite\r\npython run.py --test\r\n\r\n# Run with verbose output\r\npython run.py -v --test\r\n```\r\n\r\n## License\r\n\r\nMIT License - see LICENSE file for details.\r\n\r\n## Compatibility\r\n\r\n- **Python**: 3.7+\r\n- **Operating Systems**: Windows, macOS, Linux\r\n- **Dependencies**: None (pure Python implementation)\r\n\r\n## Roadmap\r\n\r\n### Current Status \u2705\r\n- [x] Complete Lisp interpreter\r\n- [x] Interactive REPL\r\n- [x] File evaluation\r\n- [x] Comprehensive test suite\r\n- [x] Python API\r\n- [x] CLI interface\r\n\r\n### Future Enhancements \ud83d\udea7\r\n- [ ] Macro system\r\n- [ ] Package system\r\n- [ ] Error handling improvements\r\n- [ ] Performance optimizations\r\n- [ ] Additional built-in functions\r\n- [ ] Documentation improvements\r\n\r\n## Examples and Learning\r\n\r\nFCLPY is perfect for:\r\n- Learning Lisp programming\r\n- Teaching interpreter implementation\r\n- Embedding Lisp in Python applications\r\n- Rapid prototyping of symbolic computation\r\n- Educational projects\r\n\r\n## Support\r\n\r\n- **Issues**: [GitHub Issues](https://github.com/fclpy/fclpy/issues)\r\n- **Documentation**: [Wiki](https://github.com/fclpy/fclpy/wiki)\r\n- **Source**: [GitHub Repository](https://github.com/fclpy/fclpy)\r\n\r\n---\r\n\r\n**FCLPY** - Bringing the power of Lisp to Python! \ud83d\ude80\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A Common Lisp interpreter implemented in Python",
"version": "0.1.0",
"project_urls": {
"Bug Tracker": "https://github.com/your-username/fclpy/issues",
"Documentation": "https://github.com/your-username/fclpy/wiki",
"Homepage": "https://github.com/your-username/fclpy",
"Source Code": "https://github.com/your-username/fclpy"
},
"split_keywords": [
"lisp",
" interpreter",
" common-lisp",
" programming-language",
" repl"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "deca16d84d31986732b2d5cd7c97a93a573c8b9c121f6f933aaa0491f8aaac9e",
"md5": "c8dc34ab4af60cd67504f77449626b26",
"sha256": "3c3ac7244d1259accc64e6b9188bc74eedef0d8eb7a08bef9f10cffa54c7709f"
},
"downloads": -1,
"filename": "fclpy-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c8dc34ab4af60cd67504f77449626b26",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 24741,
"upload_time": "2025-08-10T18:45:34",
"upload_time_iso_8601": "2025-08-10T18:45:34.603945Z",
"url": "https://files.pythonhosted.org/packages/de/ca/16d84d31986732b2d5cd7c97a93a573c8b9c121f6f933aaa0491f8aaac9e/fclpy-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "1935122b02cab89960dd6db4adcf46ac191341800c56fb2bf62d0eb5cbd95f79",
"md5": "8a5d85d2c51a95ff51cacaf522e63779",
"sha256": "6c00f779d9df69b4fb46c1d1c4d681782290d58e78dff643d79b2717b41a58f9"
},
"downloads": -1,
"filename": "fclpy-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "8a5d85d2c51a95ff51cacaf522e63779",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 33487,
"upload_time": "2025-08-10T18:45:36",
"upload_time_iso_8601": "2025-08-10T18:45:36.153239Z",
"url": "https://files.pythonhosted.org/packages/19/35/122b02cab89960dd6db4adcf46ac191341800c56fb2bf62d0eb5cbd95f79/fclpy-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-10 18:45:36",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "your-username",
"github_project": "fclpy",
"github_not_found": true,
"lcname": "fclpy"
}
JSON
