-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #20 from axone-protocol/docs/complete-readme
Docs/complete readme
- Loading branch information
Showing
2 changed files
with
57 additions
and
150 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,176 +1,82 @@ | ||
| #  | ||
|
|
||
| [](https://pkg.go.dev/github.com/ichiban/prolog) | ||
| [](https://github.com/ichiban/prolog/actions) | ||
| [](https://goreportcard.com/report/github.com/ichiban/prolog) | ||
| [](https://codecov.io/gh/ichiban/prolog) | ||
| [](https://github.com/avelino/awesome-go) | ||
| [](https://axone.xyz) | ||
|
|
||
| <p align="center"> | ||
| <a href="https://discord.gg/axone"><img src="https://img.shields.io/badge/Discord-7289DA?style=for-the-badge&logo=discord&logoColor=white" /></a> | ||
| <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> | ||
| <a href="https://twitter.com/axonexyz"><img src="https://img.shields.io/badge/Twitter-1DA1F2?style=for-the-badge&logo=twitter&logoColor=white" /></a> | ||
| <a href="https://blog.axone.xyz"><img src="https://img.shields.io/badge/Medium-12100E?style=for-the-badge&logo=medium&logoColor=white" /></a> | ||
| <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> | ||
| </p> | ||
|
|
||
| # Axone Prolog Virtual Machine | ||
|
|
||
| [](https://github.com/axone-protocol/prolog/actions/workflows/go.yml) | ||
| [](https://codecov.io/gh/axone-protocol/prolog) | ||
| [](https://pkg.go.dev/github.com/axone-protocol/prolog) | ||
| [](https://goreportcard.com/report/github.com/axone-protocol/prolog) | ||
| [](https://conventionalcommits.org) | ||
| [](https://github.com/axone-protocol/.github/blob/main/CODE_OF_CONDUCT.md) | ||
| [](https://opensource.org/license/mit) | ||
|
|
||
| > [!IMPORTANT] | ||
| > 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. | ||
| > 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. | ||
| > | ||
| > 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). | ||
| ## What is this? | ||
|
|
||
| `ichiban/prolog` is an embeddable **ISO Prolog** interpreter in **Go**. | ||
|
|
||
| - **Standards-compliant:** | ||
| - [ISO/IEC 13211-1:1995 Information technology — Programming languages — Prolog — Part 1: General core](https://www.iso.org/standard/21413.html) | ||
| - [A Prologue for Prolog](http://www.complang.tuwien.ac.at/ulrich/iso-prolog/prologue) | ||
| - [DCGs](https://www.complang.tuwien.ac.at/ulrich/iso-prolog/dcgs/dcgsdraft-2019-06-03.pdf) | ||
| - **Easy to integrate:** `database/sql`-like Go API | ||
| - **Highly customizable:** | ||
| - Sandboxing | ||
| - Custom predicates in Go | ||
| - Custom terms (data types) in Go | ||
|
|
||
| ## Comparison with Other Libraries | ||
|
|
||
| | | **prolog** | otto | go-lua | | ||
| | ----------- | ---------------------- | --------------- | --------------- | | ||
| | Language | ISO Prolog | ECMA Script | Lua | | ||
| | Paradigm | 🎓 Logic | Object-oriented | Object-oriented | | ||
| | Go API | 😻 `database/sql`-like | original | original | | ||
| | Declarative | ✅ | ❌ | ❌ | | ||
| | Sandboxing | ✅ | ❌ | ✅ | | ||
|
|
||
| ## Getting started | ||
|
|
||
| ### Install latest version | ||
|
|
||
| ```console | ||
| go get -u github.com/ichiban/prolog | ||
| ``` | ||
|
|
||
| ### Usage | ||
|
|
||
| #### Instantiate an interpreter | ||
|
|
||
| ```go | ||
| p := prolog.New(os.Stdin, os.Stdout) // Or `prolog.New(nil, nil)` if you don't need user_input/user_output. | ||
| ``` | ||
|
|
||
| Or, if you want a sandbox interpreter without any built-in predicates: | ||
|
|
||
| ```go | ||
| // See examples/sandboxing/main.go for details. | ||
| p := new(prolog.Interpreter) | ||
| ``` | ||
|
|
||
| #### Load a Prolog program | ||
|
|
||
| ```go | ||
| if err := p.Exec(` | ||
| human(socrates). % This is a fact. | ||
| mortal(X) :- human(X). % This is a rule. | ||
| `); err != nil { | ||
| panic(err) | ||
| } | ||
| ``` | ||
|
|
||
| Similar to `database/sql`, you can use placeholder `?` to insert Go data as Prolog data. | ||
|
|
||
| ```go | ||
| if err := p.Exec(`human(?).`, "socrates"); err != nil { // Same as p.Exec(`human("socrates").`) | ||
| panic(err) | ||
| } | ||
| ``` | ||
| `axone-protocol/prolog` is a Prolog virtual machine written in Go, designed to be embedded in blockchain environments. | ||
| It serves as the core of the [Axone protocol](https://axone.xyz) for decentralized, logic-based smart contracts. | ||
|
|
||
| #### Run the Prolog program | ||
| This project is a fork of the [ichiban/prolog](https://github.com/ichiban/prolog) repository, striving to maintain | ||
| ISO standard compliance where feasible while adapting to the unique constraints of blockchain execution. | ||
|
|
||
| ```go | ||
| sols, err := p.Query(`mortal(?).`, "socrates") // Same as p.Query(`mortal("socrates").`) | ||
| if err != nil { | ||
| panic(err) | ||
| } | ||
| defer sols.Close() | ||
| ## Deviations from the ISO Standard | ||
|
|
||
| // Iterates over solutions. | ||
| for sols.Next() { | ||
| fmt.Printf("Yes.\n") // ==> Yes. | ||
| } | ||
| The following customizations have been made to adapt the original `ichiban/prolog` implementation to the blockchain environment: | ||
|
|
||
| // Check if an error occurred while querying. | ||
| if err := sols.Err(); err != nil { | ||
| panic(err) | ||
| } | ||
| ``` | ||
| - Capped variable allocation to limit the number of variables. | ||
| - Replaced maps with ordered maps to ensure deterministic execution. | ||
| - Implemented secure integer arithmetic for functors. | ||
| - Integrated [cockroachdb/apd](https://github.com/cockroachdb/apd) for floating-point arithmetic. | ||
| - Removed support for trigonometric functions (`sin`, `cos`, `tan`, `asin`, `acos`, `atan`). | ||
| - Introduced VM hooks for enhanced Prolog execution control. | ||
| - Added support for the `Dict` term. | ||
|
|
||
| Or, if you want to query for the variable values for each solution: | ||
|
|
||
| ```go | ||
| sols, err := p.Query(`mortal(Who).`) | ||
| if err != nil { | ||
| panic(err) | ||
| } | ||
| defer sols.Close() | ||
|
|
||
| // Iterates over solutions. | ||
| for sols.Next() { | ||
| // Prepare a struct with fields which name corresponds with a variable in the query. | ||
| var s struct { | ||
| Who string | ||
| } | ||
| if err := sols.Scan(&s); err != nil { | ||
| panic(err) | ||
| } | ||
| fmt.Printf("Who = %s\n", s.Who) // ==> Who = socrates | ||
| } | ||
|
|
||
| // Check if an error occurred while querying. | ||
| if err := sols.Err(); err != nil { | ||
| panic(err) | ||
| } | ||
| ``` | ||
|
|
||
| ## The Default Language | ||
|
|
||
| `ichiban/prolog` adheres the ISO standard and comes with the ISO predicates as well as the Prologue for Prolog and DCG predicates. | ||
|
|
||
| See [the Wiki](https://github.com/ichiban/prolog/wiki) for the directives and the built-in predicates. | ||
|
|
||
| ### Top Level | ||
|
|
||
| `1pl` is an experimental top level command for testing the default language and its compliance to the ISO standard. | ||
|
|
||
| You can install it with `go install`: | ||
| ## License | ||
|
|
||
| ```console | ||
| go install github.com/ichiban/prolog/cmd/1pl@latest | ||
| ``` | ||
| Distributed under the MIT license. See `LICENSE` for more information. | ||
|
|
||
| Then, you can enter the top level with `1pl`: | ||
| ## Bug reports & feature requests | ||
|
|
||
| ```console | ||
| $(go env GOPATH)/bin/1pl [<file>...] | ||
| ``` | ||
| If you notice anything not behaving how you expected, if you would like to make a suggestion or would like | ||
| to request a new feature, please open a [**new issue**](https://github.com/axone-protocol/axoned/issues/new/choose). We appreciate any help | ||
| you're willing to give! | ||
|
|
||
| ## Extensions | ||
| > Don't hesitate to ask if you are having trouble setting up your project repository, creating your first branch or | ||
| > configuring your development environment. Mentors and maintainers are here to help! | ||
| - **[predicates](https://github.com/guregu/predicates):** Native predicates for ichiban/prolog. | ||
| - **[kagomelog](https://github.com/ichiban/kagomelog):** a Japanese morphological analyzing predicate. | ||
| ## You want to get involved? 😍 | ||
|
|
||
| ## License | ||
| So you want to contribute? Great! ❤️ We appreciate any help you're willing to give. Don't hesitate to open issues and/or | ||
| submit pull requests. | ||
|
|
||
| Distributed under the MIT license. See `LICENSE` for more information. | ||
| 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: | ||
|
|
||
| ## Contributing | ||
| - Engage in conversations with peers and experts. | ||
| - Share your insights and experiences with Axone. | ||
| - Learn from others and expand your knowledge of the protocol. | ||
|
|
||
| See `ARCHITECTURE.md` for architecture details. | ||
| The Community space serves as a hub for discussions, questions, and knowledge-sharing related to Axone. | ||
| We encourage you to actively participate and contribute to the growth of our community. | ||
|
|
||
| 1. Fork it (https://github.com/ichiban/prolog/fork) | ||
| 2. Create your feature branch (git checkout -b feature/fooBar) | ||
| 3. Commit your changes (git commit -am 'Add some fooBar') | ||
| 4. Push to the branch (git push origin feature/fooBar) | ||
| 5. Create a new Pull Request | ||
| Please check out Axone health files: | ||
|
|
||
| ## Acknowledgments | ||
| - [Contributing](https://github.com/axone-protocol/.github/blob/main/CONTRIBUTING.md) | ||
| - [Code of conduct](https://github.com/axone-protocol/.github/blob/main/CODE_OF_CONDUCT.md) | ||
|
|
||
| We would like to extend our thanks to the following individuals for their contributions to this project: | ||
| ## Acknowledgements | ||
|
|
||
| - [guregu](https://github.com/guregu) for contributing code and ideas | ||
| - [Markus Triska](https://github.com/triska) for his deep knowledge and insights on modern Prolog, as evidenced by his insightful comments on issues | ||
| - [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. | ||
| We would like to thank the following projects for their inspiration and for providing the foundation for this project: | ||
|
|
||
| We are grateful for the support and contributions of everyone involved in this project. Arigatou gozaimasu! | ||
| - [ichiban](https://github.com/ichiban) for the original Prolog implementation. |