Merge branch 'trueagi-io:main' into main

.github/workflows/common.yml

@@ -31,7 +31,7 @@ jobs:
 
     steps:
       - name: Check out repository code
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
 
       - name: Install Rust stable
         uses: actions-rs/[email protected]
@@ -57,7 +57,7 @@ jobs:
           args: cbindgen
 
       - name: Set up Python
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: ${{ inputs.python-version }}
 

.github/workflows/docs.yaml

@@ -9,8 +9,8 @@ jobs:
   deploy-docs:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
-      - uses: actions/setup-python@v4
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
         with:
           python-versoin: 3.x
       - uses: actions/cache@v2

.github/workflows/minimal.yml

@@ -21,7 +21,7 @@ jobs:
 
     steps:
       - name: Check out repository code
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
 
       - name: Install Rust stable
         uses: actions-rs/[email protected]
@@ -47,7 +47,7 @@ jobs:
           args: cbindgen
 
       - name: Set up Python
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: 3.7
 

.github/workflows/release-python.yml

@@ -20,17 +20,17 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        os: [ubuntu-20.04, macos-11]
+        os: [ubuntu-20.04, macos-13, macos-14]
       max-parallel: 3
 
     steps:
       - name: Checkout source code
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
 
       - name: Set up Python
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
-          python-version: "3.8"
+          python-version: "3.10"
 
       - run: |
           echo "REF_NAME=${{github.ref_name}}" | tee -a $GITHUB_ENV
@@ -40,10 +40,9 @@ jobs:
           echo "COMMIT_HEAD=${{github.ref_name != '' && github.ref_name || env.GITHUB_SHA}}" | tee -a $GITHUB_ENV
 
       - name: Build wheels on ${{ matrix.os }}
-        uses: pypa/cibuildwheel@v2.13.1
+        uses: pypa/cibuildwheel@v2.17.0
         env:
           CIBW_BEFORE_ALL: sh -c "./python/install-hyperonc.sh -u https://github.com/${{github.repository}}.git -r ${{env.COMMIT_HEAD}}"
-          CIBW_SKIP: "*musllinux*"
         with:
           package-dir: ./python
 
@@ -59,9 +58,9 @@ jobs:
           file_glob: true
 
       - name: Upload Artifacts
-        uses: actions/upload-artifact@v3
+        uses: actions/upload-artifact@v4
         with:
-          name: python-wheels
+          name: python-wheels-${{ matrix.os }}
           path: ./wheelhouse/*.whl
 
   publish-test-pypi:
@@ -74,9 +73,10 @@ jobs:
     needs: [build-wheels]
     if: github.event.action == 'published'
     steps:
-    - uses: actions/download-artifact@v3
+    - uses: actions/download-artifact@v4
       with:
-        name: python-wheels
+        pattern: python-wheels-*
+        merge-multiple: true
         path: dist
     - name: Publish package distributions to Test PyPI
       uses: pypa/gh-action-pypi-publish@release/v1
@@ -93,9 +93,10 @@ jobs:
     needs: [build-wheels]
     if: github.event.action == 'published'
     steps:
-    - uses: actions/download-artifact@v3
+    - uses: actions/download-artifact@v4
       with:
-        name: python-wheels
+        pattern: python-wheels-*
+        merge-multiple: true
         path: dist
     - name: Publish package distributions to PyPI
       uses: pypa/gh-action-pypi-publish@release/v1

Cargo.toml

@@ -7,11 +7,11 @@ members = [
 resolver = "2"
 
 [workspace.package]
-version = "0.1.8"
+version = "0.1.10"
 edition = "2021"
 
 [workspace.dependencies]
-hyperon = { path = "./lib", version = "0.1.8" }
+hyperon = { path = "./lib", version = "0.1.10" }
 regex = "1.5.4"
 log = "0.4.0"
 env_logger = "0.8.4"

README.md

@@ -18,7 +18,15 @@ If you want to contribute the project please see the [contribution guide](./docs
 If you find troubles with the installation, see the [Troubleshooting](#troubleshooting) section below.
 For development related instructions see the [development guide](./docs/DEVELOPMENT.md).
 
-# Prepare environment
+# Using the latest release version
+
+It is the most simple way of getting MeTTa interpreter especially if you are a Python developer.
+The following command installs the latest release version from PyPi package repository:
+```
+python3 -m pip install hyperon
+```
+
+# Prepare development environment
 
 ## Docker
 
@@ -27,6 +35,17 @@ environment. Please keep in mind that resulting image contains temporary build
 files and takes a lot of a disk space. It is not recommended to distribute it
 as an image for running MeTTa because of its size.
 
+### Ready to use image
+
+Run latest docker image from the Dockerhub:
+```
+docker run -ti trueagi/hyperon:latest
+```
+
+### Build image
+
+Docker 26.0.0 or greater version is required.
+
 Build Docker image from a local copy of the repo running:
 ```
 docker build -t trueagi/hyperon .

c/src/atom.rs

@@ -315,13 +315,13 @@ pub extern "C" fn atoms_are_equivalent(a: *const atom_ref_t, b: *const atom_ref_
     crate::atom::matcher::atoms_are_equivalent(a, b)
 }
 
-/// @brief Returns the type of an atom
+/// @brief Returns the metatype of an atom
 /// @ingroup atom_group
 /// @param[in]  atom  A pointer to an `atom_t` or an `atom_ref_t` to inspect
 /// @return An `atom_type_t` indicating the type of `atom`
 ///
 #[no_mangle]
-pub unsafe extern "C" fn atom_get_type(atom: *const atom_ref_t) -> atom_type_t {
+pub unsafe extern "C" fn atom_get_metatype(atom: *const atom_ref_t) -> atom_type_t {
     match (*atom).borrow() {
         Atom::Symbol(_) => atom_type_t::SYMBOL,
         Atom::Variable(_) => atom_type_t::VARIABLE,

c/tests/c_space.c

@@ -12,7 +12,7 @@ typedef struct _atom_list_item {
 
 void collect_variable_atoms(atom_ref_t atom, void* vec_ptr) {
     atom_vec_t* vec = vec_ptr;
-    if (atom_get_type(&atom) == VARIABLE) {
+    if (atom_get_metatype(&atom) == VARIABLE) {
         atom_vec_push(vec, atom_clone(&atom));
     }
 }

docs/DEVELOPMENT.md

@@ -1,15 +1,18 @@
 # Instructions for developers
 
-## How to check Python release procedure locally
+## How to release Python distribution packages locally
 
 Python packages are released using
 [cibuildwheel](https://pypi.org/project/cibuildwheel/). First step is to setup
 it. Usually it means setup docker and install the package from PyPi (see [setup
 instructions](https://cibuildwheel.pypa.io/en/stable/setup/#local)).
 
 There are additional preparations to be made before running it. First of all
-`libhyperonc` library should be built and installed in a build environment. It
-is done by `install-hyperonc.sh` script which is called using
+`libhyperonc` library should be built and installed in a build environment. By
+default library downloads and install version from the `main` branch of the
+`trueagi-io/hyperon-experimental` repository. If one need to use the custom
+branch then it is done by passing custom parameters to the
+`install-hyperonc.sh` script which is called using
 [CIBW_BEFORE_ALL](https://cibuildwheel.pypa.io/en/stable/options/#before-all)
 environment variable:
 ```
@@ -24,13 +27,6 @@ the Python package is copied into container automatically. Code of the
 have the code in some repo accessible from the container before starting
 release. The simplest way is to push the changes in your GitHub repo fork.
 
-Some platform are not supported. Use
-[CIBW_SKIP](https://cibuildwheel.pypa.io/en/stable/options/#build-skip) to skip
-such platforms:
-```
-export CIBW_SKIP="*musllinux*"
-```
-
 Also one can start from building the only platform to quickly check whether
 release works. This can be done using
 [CIBW_BUILD](https://cibuildwheel.pypa.io/en/stable/options/#build-skip)
@@ -42,3 +38,72 @@ export CIBW_BUILD=cp37-manylinux_x86_64
 After exporting the variables above one can start release by executing
 `cibuildwheel` from the `./python` directory of the repo. See [cibuildwheel
 documentation](https://cibuildwheel.pypa.io/en/stable/) for details.
+
+## How to update the version
+
+Usually it is needed after releasing the artifacts or before making a test
+release.
+
+There are three locations to update:
+- [/Cargo.toml](/Cargo.toml) file:
+  - `workspace.package.version` property
+  - `workspace.dependencies.hyperon.version` property
+- [/python/VERSION](/python/VERSION) file
+
+All three locations should contain the same version.
+
+## How to release binaries
+
+Use [Create a new release
+link](https://github.com/trueagi-io/hyperon-experimental/releases/new) on the
+main page of the GitHub repo. Press `Choose a tag` control and type new tag
+which should be in form of `v<next-version>` (for example if next version is
+`0.1.7` then tag is `v0.1.7`). Next version should be identical to versions
+which are written in locations mentioned in [How to update the
+version](#how-to-update-the-version) instruction. After typing the tag press
+`Create new tag on publish`. Now press `Generate release notes` button. It will
+automatically fill the `Release title` and `Release description` fields. Tick
+`Set as a pre-release` checkbox if needed and press `Publish release` button.
+Now you have published new GitHub release and triggered a job to build release
+artifacts.
+
+After release job is finished one need to approve publishing artifacts to the
+PyPi repository. Before approving one can download and test Python wheels
+built. To check the job status go the `Actions/release-pyhon` page, and select
+last workflow run. Links to the archives with the artifacts are located at the
+bottom of the page.
+
+If distribution wheels are good then one can approve the publishing process. At
+the top of the workflow run page there are two blocks `Publish to Test PyPi`
+and `Publish to PyPi`. First press `Publish to Test PyPi` block approve it and
+wait for publishing. It is critical to start from Test PyPi because release
+cannot be removed from the PyPi after publishing.
+
+After release is published check it can be installed executing:
+```
+python3 -m pip install --index-url https://test.pypi.org/simple/ hyperon
+```
+Check that the latest published version was downloaded and installed. If you
+are making a test release then you should not publish it to the PyPi. If it is
+a production release then proceed with `Publish to PyPi` block.
+
+## How to check release job in fork
+
+First you need to select the test release version. It should contain an
+additional version digit after the latest officially released version. Let's
+say the latest released version is `0.1.7`. Then the test release version
+should be `0.1.7.x` for instance `0.1.7.1`. Start from 1 and increment it after
+each release you published successfully.
+
+Make a separate branch to release the code. It is not necessary but it is
+highly recommended to not pollute the main branch of the fork. In order to be
+able releasing from the branch one need to temporary make it default branch. It
+is done by using GitHub repo `Settings/General/Default branch` control.
+
+[Update the version](#how-to-update-the-version) in the branch to the test
+release version you constructed. Commit and push this change in your test
+branch. Now you are ready to make a test release. See [release
+binaries instruction](#how-to-release-binaries).
+
+After testing the release procedure remove the commit with version update from
+your branch. And set default branch setting to the previous value.

lib/src/atom/matcher.rs

@@ -1116,32 +1116,44 @@ pub fn match_result_product(prev: MatchResultIter, next: MatchResultIter) -> Mat
     Box::new(prev.merge(&next).into_iter())
 }
 
+/// Applies bindings to atom and return it (see [apply_bindings_to_atom_mut]).
+#[inline]
+pub fn apply_bindings_to_atom_move(mut atom: Atom, bindings: &Bindings) -> Atom {
+    apply_bindings_to_atom_mut(&mut atom, bindings);
+    atom
+}
+
 /// Applies bindings to atom. Function replaces all variables in atom by
 /// corresponding bindings.
 ///
 /// # Examples
 ///
 /// ```
 /// use hyperon::*;
-/// use hyperon::atom::matcher::apply_bindings_to_atom;
+/// use hyperon::atom::matcher::apply_bindings_to_atom_mut;
 ///
 /// let binds = bind!{ y: expr!("Y") };
-/// let atom = apply_bindings_to_atom(&expr!("+" "X" y), &binds);
+/// let mut atom = expr!("+" "X" y);
+/// apply_bindings_to_atom_mut(&mut atom, &binds);
 ///
 /// assert_eq!(atom, expr!("+" "X" "Y"));
 /// ```
-pub fn apply_bindings_to_atom(atom: &Atom, bindings: &Bindings) -> Atom {
-    let mut result = atom.clone();
+pub fn apply_bindings_to_atom_mut(atom: &mut Atom, bindings: &Bindings) {
+    let trace_atom = match log::log_enabled!(log::Level::Trace) {
+        true => Some(atom.clone()),
+        false => None,
+    };
     if !bindings.is_empty() {
-        result.iter_mut().for_each(|atom| match atom {
+        atom.iter_mut().for_each(|atom| match atom {
             Atom::Variable(var) => {
                 bindings.resolve(var).map(|value| *atom = value);
             },
             _ => {},
         });
     }
-    log::trace!("apply_bindings_to_atom: {} | {} -> {}", atom, bindings, result);
-    result
+    if let Some(atom_copy) = trace_atom {
+        log::trace!("apply_bindings_to_atom: {} | {} -> {}", atom_copy, bindings, atom);
+    }
 }
 
 /// Applies bindings `from` to the each value from bindings `to`.