Skip to content

Commit d7a95c1

Browse files
ccamelccamel
committed
docs(README): complete repository description
1 parent 1824698 commit d7a95c1

File tree

1 file changed

+56
-150
lines changed

1 file changed

+56
-150
lines changed

‎README.md

Lines changed: 56 additions & 150 deletions
Original file line numberDiff line numberDiff line change
@@ -1,176 +1,82 @@
1-
# ![prolog - the only reasonable scripting engine for Go](prolog.gif)
2-
3-
[![Go Reference](https://pkg.go.dev/badge/github.com/ichiban/prolog.svg)](https://pkg.go.dev/github.com/ichiban/prolog)
4-
[![Actions Status](https://github.com/ichiban/prolog/actions/workflows/go.yml/badge.svg)](https://github.com/ichiban/prolog/actions)
5-
[![Go Report Card](https://goreportcard.com/badge/github.com/ichiban/prolog)](https://goreportcard.com/report/github.com/ichiban/prolog)
6-
[![codecov](https://codecov.io/gh/ichiban/prolog/branch/main/graph/badge.svg?token=2FC3PZY7LN)](https://codecov.io/gh/ichiban/prolog)
7-
[![Mentioned in Awesome Go](https://awesome.re/mentioned-badge.svg)](https://github.com/avelino/awesome-go)
1+
[![axone github banner](https://raw.githubusercontent.com/axone-protocol/.github/main/profile/static/axone-banner.png)](https://axone.xyz)
2+
3+
<p align="center">
4+
<a href="https://discord.gg/axone"><img src="https://img.shields.io/badge/Discord-7289DA?style=for-the-badge&logo=discord&logoColor=white" /></a> &nbsp;
5+
<a href="https://www.linkedin.com/company/axone-protocol/"><img src="https://img.shields.io/badge/LinkedIn-0077B5?style=for-the-badge&logo=linkedin&logoColor=white" /></a> &nbsp;
6+
<a href="https://twitter.com/axonexyz"><img src="https://img.shields.io/badge/Twitter-1DA1F2?style=for-the-badge&logo=twitter&logoColor=white" /></a> &nbsp;
7+
<a href="https://blog.axone.xyz"><img src="https://img.shields.io/badge/Medium-12100E?style=for-the-badge&logo=medium&logoColor=white" /></a> &nbsp;
8+
<a href="https://www.youtube.com/channel/UCiOfcTaUyv2Szv4OQIepIvg"><img src="https://img.shields.io/badge/YouTube-FF0000?style=for-the-badge&logo=youtube&logoColor=white" /></a>
9+
</p>
10+
11+
# Axone Prolog Virtual Machine
12+
13+
[![build](https://img.shields.io/github/actions/workflow/status/axone-protocol/prolog/go.yml?label=build&style=for-the-badge&logo=github)](https://github.com/axone-protocol/prolog/actions/workflows/go.yml)
14+
[![codecov](https://img.shields.io/codecov/c/github/axone-protocol/prolog?style=for-the-badge&token=O3FJO5QDCA&logo=codecov)](https://codecov.io/gh/axone-protocol/prolog)
15+
[![GoDoc](https://img.shields.io/badge/godoc-reference-5272B4.svg?style=for-the-badge&logo=go)](https://pkg.go.dev/github.com/axone-protocol/prolog)
16+
[![Go Report Card](https://goreportcard.com/badge/github.com/axone-protocol/prolog?style=for-the-badge)](https://goreportcard.com/report/github.com/axone-protocol/prolog)
17+
[![conventional commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-yellow.svg?style=for-the-badge&logo=conventionalcommits)](https://conventionalcommits.org)
18+
[![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg?style=for-the-badge)](https://github.com/axone-protocol/.github/blob/main/CODE_OF_CONDUCT.md)
19+
[![license](https://img.shields.io/github/license/axone-protocol/prolog.svg?label=License&style=for-the-badge)](https://opensource.org/license/mit)
820

921
> [!IMPORTANT]
10-
> This repository is a *hard fork* of [ichiban/prolog](https://github.com/ichiban/prolog), customized to meet the specific requirements of the [Axone protocol](https://github.com/axone-protocol). It is maintained independently for our use case, and upstream updates may not be regularly integrated.
22+
> This repository is a _hard fork_ of [ichiban/prolog](https://github.com/ichiban/prolog), customized to meet the specific requirements of the [Axone protocol](https://github.com/axone-protocol). It is maintained independently for our use case, and upstream updates may not be regularly integrated.
1123
>
1224
> For the original, general-purpose Prolog implementation or to contribute to the broader community, please visit the [ichiban/prolog repository](https://github.com/ichiban/prolog).
1325
1426
## What is this?
1527

16-
`ichiban/prolog` is an embeddable **ISO Prolog** interpreter in **Go**.
17-
18-
- **Standards-compliant:**
19-
- [ISO/IEC 13211-1:1995 Information technology — Programming languages — Prolog — Part 1: General core](https://www.iso.org/standard/21413.html)
20-
- [A Prologue for Prolog](http://www.complang.tuwien.ac.at/ulrich/iso-prolog/prologue)
21-
- [DCGs](https://www.complang.tuwien.ac.at/ulrich/iso-prolog/dcgs/dcgsdraft-2019-06-03.pdf)
22-
- **Easy to integrate:** `database/sql`-like Go API
23-
- **Highly customizable:**
24-
- Sandboxing
25-
- Custom predicates in Go
26-
- Custom terms (data types) in Go
27-
28-
## Comparison with Other Libraries
29-
30-
| | **prolog** | otto | go-lua |
31-
| ----------- | ---------------------- | --------------- | --------------- |
32-
| Language | ISO Prolog | ECMA Script | Lua |
33-
| Paradigm | 🎓 Logic | Object-oriented | Object-oriented |
34-
| Go API | 😻 `database/sql`-like | original | original |
35-
| Declarative | ✅ | ❌ | ❌ |
36-
| Sandboxing | ✅ | ❌ | ✅ |
37-
38-
## Getting started
39-
40-
### Install latest version
41-
42-
```console
43-
go get -u github.com/ichiban/prolog
44-
```
45-
46-
### Usage
47-
48-
#### Instantiate an interpreter
49-
50-
```go
51-
p := prolog.New(os.Stdin, os.Stdout) // Or `prolog.New(nil, nil)` if you don't need user_input/user_output.
52-
```
53-
54-
Or, if you want a sandbox interpreter without any built-in predicates:
55-
56-
```go
57-
// See examples/sandboxing/main.go for details.
58-
p := new(prolog.Interpreter)
59-
```
60-
61-
#### Load a Prolog program
62-
63-
```go
64-
if err := p.Exec(`
65-
human(socrates). % This is a fact.
66-
mortal(X) :- human(X). % This is a rule.
67-
`); err != nil {
68-
panic(err)
69-
}
70-
```
71-
72-
Similar to `database/sql`, you can use placeholder `?` to insert Go data as Prolog data.
73-
74-
```go
75-
if err := p.Exec(`human(?).`, "socrates"); err != nil { // Same as p.Exec(`human("socrates").`)
76-
panic(err)
77-
}
78-
```
28+
`axone-protocol/prolog` is a Prolog virtual machine written in Go, designed to be embedded in blockchain environments.
29+
It serves as the core of the [Axone protocol](https://axone.xyz) for decentralized, logic-based smart contracts.
7930

80-
#### Run the Prolog program
31+
This project is a fork of the [ichiban/prolog](https://github.com/ichiban/prolog) repository, striving to maintain
32+
ISO standard compliance where feasible while adapting to the unique constraints of blockchain execution.
8133

82-
```go
83-
sols, err := p.Query(`mortal(?).`, "socrates") // Same as p.Query(`mortal("socrates").`)
84-
if err != nil {
85-
panic(err)
86-
}
87-
defer sols.Close()
34+
## Deviations from the ISO Standard
8835

89-
// Iterates over solutions.
90-
for sols.Next() {
91-
fmt.Printf("Yes.\n") // ==> Yes.
92-
}
36+
The following customizations have been made to adapt the original `ichiban/prolog` implementation to the blockchain environment:
9337

94-
// Check if an error occurred while querying.
95-
if err := sols.Err(); err != nil {
96-
panic(err)
97-
}
98-
```
38+
- Capped variable allocation to limit the number of variables.
39+
- Replaced maps with ordered maps to ensure deterministic execution.
40+
- Implemented secure integer arithmetic for functors.
41+
- Integrated [cockroachdb/apd](https://github.com/cockroachdb/apd) for floating-point arithmetic.
42+
- Removed support for trigonometric functions (`sin`, `cos`, `tan`, `asin`, `acos`, `atan`).
43+
- Introduced VM hooks for enhanced Prolog execution control.
44+
- Added support for the `Dict` term.
9945

100-
Or, if you want to query for the variable values for each solution:
101-
102-
```go
103-
sols, err := p.Query(`mortal(Who).`)
104-
if err != nil {
105-
panic(err)
106-
}
107-
defer sols.Close()
108-
109-
// Iterates over solutions.
110-
for sols.Next() {
111-
// Prepare a struct with fields which name corresponds with a variable in the query.
112-
var s struct {
113-
Who string
114-
}
115-
if err := sols.Scan(&s); err != nil {
116-
panic(err)
117-
}
118-
fmt.Printf("Who = %s\n", s.Who) // ==> Who = socrates
119-
}
120-
121-
// Check if an error occurred while querying.
122-
if err := sols.Err(); err != nil {
123-
panic(err)
124-
}
125-
```
126-
127-
## The Default Language
128-
129-
`ichiban/prolog` adheres the ISO standard and comes with the ISO predicates as well as the Prologue for Prolog and DCG predicates.
130-
131-
See [the Wiki](https://github.com/ichiban/prolog/wiki) for the directives and the built-in predicates.
132-
133-
### Top Level
134-
135-
`1pl` is an experimental top level command for testing the default language and its compliance to the ISO standard.
136-
137-
You can install it with `go install`:
46+
## License
13847

139-
```console
140-
go install github.com/ichiban/prolog/cmd/1pl@latest
141-
```
48+
Distributed under the MIT license. See `LICENSE` for more information.
14249

143-
Then, you can enter the top level with `1pl`:
50+
## Bug reports & feature requests
14451

145-
```console
146-
$(go env GOPATH)/bin/1pl [<file>...]
147-
```
52+
If you notice anything not behaving how you expected, if you would like to make a suggestion or would like
53+
to request a new feature, please open a [**new issue**](https://github.com/axone-protocol/axoned/issues/new/choose). We appreciate any help
54+
you're willing to give!
14855

149-
## Extensions
56+
> Don't hesitate to ask if you are having trouble setting up your project repository, creating your first branch or
57+
> configuring your development environment. Mentors and maintainers are here to help!
15058
151-
- **[predicates](https://github.com/guregu/predicates):** Native predicates for ichiban/prolog.
152-
- **[kagomelog](https://github.com/ichiban/kagomelog):** a Japanese morphological analyzing predicate.
59+
## You want to get involved? 😍
15360

154-
## License
61+
So you want to contribute? Great! ❤️ We appreciate any help you're willing to give. Don't hesitate to open issues and/or
62+
submit pull requests.
15563

156-
Distributed under the MIT license. See `LICENSE` for more information.
64+
We believe that collaboration is key to the success of the Axone project. Join our Community discussions on the [Community space](https://github.com/orgs/axone-protocol/discussions) to:
15765

158-
## Contributing
66+
- Engage in conversations with peers and experts.
67+
- Share your insights and experiences with Axone.
68+
- Learn from others and expand your knowledge of the protocol.
15969

160-
See `ARCHITECTURE.md` for architecture details.
70+
The Community space serves as a hub for discussions, questions, and knowledge-sharing related to Axone.
71+
We encourage you to actively participate and contribute to the growth of our community.
16172

162-
1. Fork it (https://github.com/ichiban/prolog/fork)
163-
2. Create your feature branch (git checkout -b feature/fooBar)
164-
3. Commit your changes (git commit -am 'Add some fooBar')
165-
4. Push to the branch (git push origin feature/fooBar)
166-
5. Create a new Pull Request
73+
Please check out Axone health files:
16774

168-
## Acknowledgments
75+
- [Contributing](https://github.com/axone-protocol/.github/blob/main/CONTRIBUTING.md)
76+
- [Code of conduct](https://github.com/axone-protocol/.github/blob/main/CODE_OF_CONDUCT.md)
16977

170-
We would like to extend our thanks to the following individuals for their contributions to this project:
78+
## Acknowledgements
17179

172-
- [guregu](https://github.com/guregu) for contributing code and ideas
173-
- [Markus Triska](https://github.com/triska) for his deep knowledge and insights on modern Prolog, as evidenced by his insightful comments on issues
174-
- [Prof. Ulrich Neumerkel](https://github.com/UWN) for valuable guidance, his [works on ISO standards](http://www.complang.tuwien.ac.at/ulrich/iso-prolog/), [the Prologue for Prolog](http://www.complang.tuwien.ac.at/ulrich/iso-prolog/prologue), and DCGs.
80+
We would like to thank the following projects for their inspiration and for providing the foundation for this project:
17581

176-
We are grateful for the support and contributions of everyone involved in this project. Arigatou gozaimasu!
82+
- [ichiban](https://github.com/ichiban) for the original Prolog implementation.

0 commit comments

Comments
 (0)