(λblog.rainbyte)

Restore files on RPi homelab server

2026-03-08T03:06:00-03:00

Posted on 2026-03-08 03:06:00 by rainbyte

Tags: debian kernel linux rpi

I lost connection to my Raspberry Pi homelab server and then I found it wouldn't respond to SSH. After connecting a debug screen, I discovered a message about corrupted libapparmor library.

Since the RPi uses aarch64 architecture, I wasn't able to easily chroot from my x86 PC, so I had to restore affected files directly from .deb packages to the RPi microsd card.

This guide explains how to recover a corrupted Debian system on Raspberry Pi by manually extracting and replacing system files. So let's go!

Summary

RPi server stopped responding
Screen showed libapparmor corruption error
Cannot chroot because RPi is aarch64, PC is on x86
Restored broken library from .deb directly to microsd
Booted again, but got kernel panic
Restored kernel modules from .deb to microsd
Booted successfully
Installed debsums to verify packages integrity
Reinstalled other broken packages via apt
System fully restored

Solve the first error

These are the step-by-step instructions:

First, identify the microsd card partition and mount it:
```
mkdir /tmp/rootfs
sudo mount /dev/sdXN /tmp/rootfs
```
Notes:
- Find the correct device with lsblk or blkid
- Replace sdXN with that partition (eg. sdb2)
Identify the corrupted file by checking error messages from the boot screen, which in my case mentioned about issues with libapparmor library

Get the right .deb package according to Debian system version:

curl -o libapparmor1_4.1.0-1_arm64.deb \
  http://http.us.debian.org/debian/pool/main/a/apparmor/libapparmor1_4.1.0-1_arm64.deb

Note: check /etc/os-release on your system for the correct version

Extract data.tar.xz from package contents:
```
ar x libapparmor1_4.1.0-1_arm64.deb
```
Note: it can be data.tar.gz for older packages
Extract data contents
- For modern .xz compressed archives:
```
tar -xJf data.tar.xz
```
- For older .gz compressed archives:
```
tar -xzf data.tar.gz
```
Verify if the library is corrupted by comparing the extracted file with the one on the mounted microsd card partition:
```
cmp -s \
  usr/lib/aarch64-linux-gnu/libapparmor.so.1.24.2 \
  /tmp/rootfs/lib/aarch64-linux-gnu/libapparmor.so.1.24.2 \
  && echo "MATCH" || echo "MISMATCH"
```
Note: it says MATCH if files are identical, or MISMATCH if they differ

Replace the library if there is a mismatch

cp \
  usr/lib/aarch64-linux-gnu/libapparmor.so.1.24.2 \
  /tmp/rootfs/lib/aarch64-linux-gnu/libapparmor.so.1.24.2

Run the cmp command again to confirm the files now match

Fix permissions if needed

sudo chmod 644 /tmp/rootfs/lib/aarch64-linux-gnu/libapparmor.so.1.24.2

Kernel recovery

After fixing the library, I booted the microsd card but got a kernel panic, which indicated kernel modules were also corrupted.

So these steps were the next to be applied:

Download and extract kernel package

curl -o linux-image-6.12.62+rpt-rpi-v8_6.12.62-1+rpt1_arm64.deb https://archive.raspberrypi.com/debian/pool/main/l/linux/linux-image-6.12.62+rpt-rpi-v8_6.12.62-1+rpt1_arm64.deb
ar x linux-image-6.12.62+rpt-rpi-v8_6.12.62-1+rpt1_arm64.deb
tar -xJf data.tar.xz

Note: Use the kernel version matching your system

Compare boot files between the extracted package and mounted microsd fat32 boot partition:

cmp -s \
  boot/vmlinuz-6.12.62+rpt-rpi-v8 \
  /tmp/rootfs/boot/vmlinuz-6.12.62+rpt-rpi-v8 \
  && echo "MATCH" || echo "MISMATCH"

cmp -s \
  boot/config-6.12.62+rpt-rpi-v8 \
  /tmp/rootfs/boot/config-6.12.62+rpt-rpi-v8 \
  && echo "MATCH" || echo "MISMATCH"

cmp -s \
  boot/System.map-6.12.62+rpt-rpi-v8 \
  /tmp/rootfs/boot/System.map-6.12.62+rpt-rpi-v8 \
  && echo "MATCH" || echo "MISMATCH"

Generate checksums for modules from the extracted package:

cd usr/lib/modules/6.12.62+rpt-rpi-v8/
find . -type f -exec sha256sum {} \; | sort > /tmp/hashes_orig.txt

Generate checksums for modules on the microsd card:

cd /tmp/rootfs/usr/lib/modules/6.12.62+rpt-rpi-v8/
find . -type f -exec sha256sum {} \; | sort > /tmp/hashes_card.txt

Note: being inside is needed to have same output

Compare the two checksums lists:

diff -u /tmp/hashes_orig.txt /tmp/hashes_card.txt

If there are differences then replace affected modules by copying the entire modules directory or at least overriding the broken files:
```
sudo cp -r \
  usr/lib/modules/6.12.62+rpt-rpi-v8/* \
  /tmp/rootfs/usr/lib/modules/6.12.62+rpt-rpi-v8/
```

Verify and repair packages

Once the system booted, in order to verify package integrity I got some tools:

Install debsums

sudo apt update
sudo apt install debsums

Run a silent check to list only corrupted files:
```
sudo debsums -s
```

For each corrupted package do a reinstall, example:

sudo apt install --reinstall \
  libacl1 libassuan9 libcamera0.6 libcc1-0 libcrypt-dev \
  libxmuu1 rpi-usb-gadget vim-common

Note: replace with the packages shown by debsums

Verify integrity again
```
sudo debsums -s
```
Note: if no output, then all packages are intact

Conclusion

The system is now fully restored!

This process saved me from re-imaging the microsd card and losing all configuration.

It seems I must use an UPS next time >.<

Happy hacking! 🐱

Comments are not open for this post yet.

Install NVIDIA driver on Debian Trixie

2026-03-05T01:56:00-03:00

Posted on 2026-03-05 01:56:00 by rainbyte

Tags: cuda debian hardware kernel linux nvidia

I needed to install NVIDIA driver 590 on Debian 13 (Trixie) because vLLM and Llama.cpp will require CUDA 13.1, but the Debian repo's driver 550 only provides CUDA 12.4.

So this guide covers two installation methods:

Debian repo
- simpler management
- officially supported
- limited to CUDA 12.4
NVIDIA repo
- provides CUDA 13.1 with driver 590
- recommended for LLM engines

TLDR

Choose the appropriate method:

Requirement	Method to be used
CUDA 12.4 (driver 550)	Debian repo method
CUDA 13.1 (driver 590)	NVIDIA repo method

Both methods will require:

Removing old packages
Installing headers
Rebooting when ready

Debian repo method

This method is simpler and works well for most cases.

For Debian 13 (Trixie) the steps are these:

Remove old NVIDIA packages

sudo apt purge "*nvidia*"
sudo apt autoremove

To enable packages edit /etc/apt/sources.list and ensure each repo includes these attributes:
```
contrib non-free non-free-firmware
```
Update package definitions
```
sudo apt update
```
Install essential dependencies
```
sudo apt install linux-headers-amd64 firmware-misc-nonfree
```
Note: firmware is explicit because nvidia-driver package doesn't indicate a dependency on it

Install NVIDIA driver

sudo apt install nvidia-driver nvidia-kernel-dkms

Reboot
```
sudo reboot
```
Install CUDA dependencies (optional)
```
sudo apt install nvidia-cuda-toolkit nvidia-cuda-dev nvidia-cuda-toolkit-gcc
```
Note: CUDA is required by LLM engines like vLLM and Llama.cpp

NVIDIA repo method

The NVIDIA repository provides a compute-only installation that avoids X11 dependencies, making it ideal for headless servers like mine.

Warning: all steps must be fully completed before rebooting, otherwise the system will be left unbootable without the driver!

Remove old NVIDIA packages

sudo apt purge "*nvidia*"
sudo apt autoremove

Add NVIDIA repository

wget https://developer.download.nvidia.com/compute/cuda/repos/debian13/sbsa/cuda-keyring_1.1-1_all.deb
dpkg -i cuda-keyring_1.1-1_all.deb
sudo apt update

Install compute-only system dependencies
```
sudo apt install nvidia-driver-cuda nvidia-kernel-open-dkms
```
Note: this is a headless installation that avoids X11 dependencies!
Reboot system
```
sudo reboot
```
Verify driver is there by running vendor provided cli tool:
```
nvidia-smi
```
Note: this shows power usage, temperature, etc

Install CUDA dependencies (optional)

sudo apt install cuda-compiler-13-1 cuda-libraries-13-1
sudo apt install cuda-libraries-dev-13-1

Note: CUDA is required by LLM engines like vLLM and Llama.cpp

Add CUDA bin directory to PATH env var with one of these commands:
- fish shell:
```
fish_add_path /usr/local/cuda/bin
```
- bash shell:
```
export PATH=${PATH}:/usr/local/cuda/bin
```

Provide cicc and nvcc at /usr/bin

sudo update-alternatives \
    --install /usr/bin/nvcc nvcc /usr/local/cuda/bin/nvcc 100
sudo update-alternatives \
    --install /usr/bin/cicc cicc /usr/local/cuda/nvvm/bin/nvcc 100

Check CUDA nvcc availability
```
nvcc --version
```

Export environment variables

# Using the symlink as base ensures minor updates are still compatible
export CUDA_HOME="/usr/local/cuda"

# Add NVCC compiler and CICC internal tools to PATH
export PATH="$CUDA_HOME/bin:$CUDA_HOME/nvvm/bin:$PATH"

# Some headers are nested, like cub/cub.cuh
export CPATH="$CUDA_HOME/include/cccl:$CUDA_HOME/include:$CPATH"

# Linking paths: stubs provides -lcuda when building without a live GPU
export LIBRARY_PATH="$CUDA_HOME/lib64:$CUDA_HOME/lib64/stubs:$LIBRARY_PATH"

# Runtime paths: omit stubs here to avoid runtime conflicts
export LD_LIBRARY_PATH="$CUDA_HOME/lib64:$LD_LIBRARY_PATH"

Note: this will be required by LLM engines to recognize CUDA libraries

To make these permanent, add them to shell's config file:
- fish: ~/.config/fish/config.fish
- bash: ~/.bashrc

Conclusion

Follow NVIDIA repo instructions if you need CUDA 13.1 and 590 driver, otherwise just use the drivers provided in Debian official repo.

Happy hacking! 🐱

Comments are not open for this post yet.

Migration from fronma library to inhouse frontmatter parsing

2026-02-10T03:29:00-03:00

Posted on 2026-02-10 03:29:00 by rainbyte

Tags: rust blog refactoring

I've been using the fronma library for my static blog generator for more than four years since I migrated my blog from Haskell to Rust implementation.

After a period of inactivity, now I reactivated my blog and started looking at the code again. That's when I noticed how much I could improve it!

Over time I realized I didn't need most of what fronma provided, even if it was fine at the beginning I noticed dependencies are huge for my usecase.

Just take a look, my frontmatter format is very simple:

Page fields:
- title (just this one)
Blog post fields:
- title
- author
- published
- tags
- language (optional)
- commentsIssue (optional)

As you can see I'm not using complex nesting, custom validators, multiple date formats, or any advanced conversions from YAML format.

Having all those unused parts means depending on all serde machinery, including serde_yaml which was deprecated 3 years ago, and other big dependencies.

Another reason to change was learning itself!

Given that I built this blog generator to understand how things work in Rust, sticking with fronma meant relying on a library for something I could implement myself.

The migration

The first thing I did was implementing inline frontmatter parsing in a compatible way before removing fronma, so that almost all the existing code was kept untouched.

Here is what was changed.

Old dependencies

My target was removing all these dependencies from Cargo.toml:

fronma = "0.4"
serde = { version = "1.0", features = ["derive"] }
serde_json = "1.0.149"
serde_yaml = "0.9"

And in the end I was able to do it.

New approach

Just using the standard library and TryFrom trait instead of an external frontmatter parsing library.

The idea was to apply traditional string processing subroutines and common data structures.

Code size

Old implementation size:
- More than 120 Kb in obvious dependencies D:
  - 4 Kb just from the fronma library itself
  - 82 Kb from serde serialization framework
  - 40 Kb from serde_yaml lib (deprecated)
- And many more, but I stopped counting there...
New implementation size:
- 187 lines in my src/main.rs
- This one is tiny! :D

Implementation details

I wrote a generic Frontmatter::parse function that works with any struct type comaptible with TryFrom<HashMap<String, String>> trait.

The parsing flow:

Initialize empty HashMap<String, String>
Read content and extract frontmatter lines between --- delimiters
Parse each line as key: value and append into the hashmap
Use TryFrom to convert the hashmap to a typed struct

Here's the function skeleton:

impl<'a, T> Frontmatter<'a, T>
    where T: TryFrom<HashMap<String, String>, Error = String>
{
    fn parse(contents: &'a str) -> Result<Self, String> {
        // Parse frontmatter into HashMap
        // Validate required fields
        // Return typed Frontmatter
    }
}

Each header type should be compatible TryFrom trait, like this one:

impl TryFrom<HashMap<String, String>> for PageHeaders {
    type Error = String;

    fn try_from(
        map: HashMap<String, String>
    ) -> Result<Self, Self::Error> {
        match map.get("title") {
            Some(title) => Ok(Self {
                title: title.clone(),
            }),
            None => Err("Missing title in frontmatter".to_string()),
        }
    }
}

For blog posts validation is stricter, but simple to understand:

impl TryFrom<HashMap<String, String>> for PostHeaders {
    type Error = String;

    fn try_from(
        map: HashMap<String, String>
    ) -> Result<Self, Self::Error> {
        let title = match map.get("title") {
            Some(title) => title.clone(),
            None => return Err(
                "Missing title in frontmatter".to_string()
            ),
        };
        let author = match map.get("author") {
            Some(author) => author.clone(),
            None => return Err(
                "Missing author in frontmatter".to_string()
            ),
        };
        let published = match map.get("published") {
            Some(published) => published.clone(),
            None => return Err(
                "Missing published in frontmatter".to_string()
            ),
        };
        let tags = match map.get("tags") {
            Some(tags) => tags.clone(),
            None => return Err(
                "Missing tags in frontmatter".to_string()
            ),
        };
        let language = map.get("language").cloned();
        let comments_issue =
            map.get("commentsIssue").cloned();

        Ok(Self {
            title,
            author,
            published,
            tags,
            language,
            comments_issue,
        })
    }
}

Usage in main stayed the same, except for these two lines which called my own parsing wrappers in order to keep code readable:

...
let fronma = PageHeaders::parse(&contents)?;
...
let fronma = PostHeaders::parse(&contents)?;
...

As you can see I'm passing contents as reference, so the result will internally borrow the post body from there as an slice, to avoid the costly operation of cloning the data into a separated String.

Immediate benefits

1. Reduced dependencies

My project now depends only on what I actually use, avoiding fronma and serde_yaml.

2. Better understanding

Now I know exactly how frontmatter parsing works in my codebase, as it is just a few lines of code.

In case of debugging, I won't need to browse for library source code.

3. Customization

I can easily extend the parser:

Support different delimiter formats
Add per-field validators
Implement field transformations

4. Test coverage

To verify parsing worked correctly for my usecase I created a set of tests.

There were some issues at the beginning with whitespace, but I solved them by using the explicit \n\ syntax for avoiding spaces on multiline strings.

Each test ended up very similar to this one:

#[test]
fn post_header_good() {
    let contents = "---\n\
        title: How-to decrease gnome title-bar height\n\
        author: rainbyte\n\
        published: 2015-07-02 03:15:07\n\
        tags: gnome, snippets, css\n\
        ---\n\
        abc\n\
        def";
    let result = PostHeaders::parse(contents);
    let fronma = result.unwrap();
    assert_eq!(
        PostHeaders {
            title: "How-to decrease gnome title-bar height"
                .to_string(),
            author: "rainbyte".to_string(),
            published: "2015-07-02 03:15:07".to_string(),
            tags: "gnome, snippets, css".to_string(),
            language: None,
            comments_issue: None,
        },
        fronma.headers
    );
    assert_eq!(
        "abc\n\
        def",
        fronma.body
    )
}

So as result all my old posts were rendered to exactly the same html as before, bit by bit!

Future ideas

Currently most of the fields are saved as strings, but now that I have more control over the types I'm planning to type check them by using stricter timedate and collection types.

Also given that I reactivated my blog and will be focusing on Rust development, I'm planning to extend it with more Rust-related content.

Conclusion

Migrating from fronma to inline inhouse parsing was rewarding, given that I reduced dependencies, expanded my knowledge, and add some test coverage.

For my simple use case, custom parsing is the best choice, and removing huge dependencies is sometimes the right kind of growth for a project.

Happy hacking 🐱

Comments are not open for this post yet.

VSCode column rulers

2022-09-08T21:25:00-03:00

Posted on 2022-09-08 21:25:00 by rainbyte

Tags: colors customization vscode

Today we will configure VSCode to add custom column rulers to measure text width. This feature doesn't require any 3rd party extension. Rulers are useful to indicate us when a line of code is getting too large.

I recommend a width of maximum 74 or 80 columns for programming code. That setup is convenient to allow showing files side-by-side.

VSCode provides color and column attributes to customize each ruler. The colors are expressed by name or as hexadecimal values, and the columns are just numbers.

Configuration steps

Follow these steps to create as many column rulers as you want:

Open VSCode
Launch command palette (press ctrl+shift+p)
Enter one of the following commands to edit config:
- Open User Settings (JSON)
  - This one affects all VSCode instances (global config)
- Open Workspace Settings (JSON)
  - This one affects only the current project (folder config)
  - Config will be saved in .vscode/settings.json
To set 2 custom column rulers add a section similar to this:
```
{
    "editor.rulers": [
        60,
        {
            "column": 80,
            "color": "#f008"
        },
    ],
}
```
Notes:
- This config creates a 1st ruler at column 60 with default color, and a 2nd ruler with explicit column and color fields.
- All the values can be changed as wanted, and even more rulers can be added.
Save the config to apply the changes each time is modified.

Happy hacking 🐱

Comments are not open for this post yet.

VSCode title-bar colors

2022-09-03T15:02:00-03:00

Posted on 2022-09-03 15:02:00 by rainbyte

Tags: colors customization organization vscode

Today's objective is to highlight different projects folders in VSCode by changing the window title-bars with specific colors. It will be similar to the Peacock extension but without any dependencies.

VSCode allows some UI customization via .json settings, there are 2 commands to access config files:

Open User Settings (JSON)
Open Workspace Settings (JSON)

In this case the Workspace command is preferred, given that it affects only the current folder opened in VSCode.

Configuration steps

Open project folder with VSCode
Launch command palette (press ctrl+shift+p)
Enter Open Workspace Settings (JSON) command

To set the custom title-bar color add a code similar to this:

{
    "workbench.colorCustomizations": {
        "titleBar.activeBackground": "#0f0",
        "titleBar.activeForeground": "#000",
        "titleBar.inactiveBackground": "#0f09",
        "titleBar.inactiveForeground": "#0009"
    }
}

Note: the numbers can be changed to select other colors

Have fun! Happy hacking 🐱

Comments are not open for this post yet.

.NET Solutions and Projects for C#

2022-08-24T23:28:00-03:00

Posted on 2022-08-24 23:28:00 by rainbyte

Tags: c# dotnet vscode

This publication is a follow up of the VSCode C# setup post

.NET Solutions

The dotnet tool allows us to create projects with the dotnet new subcommand, and because of that it is easy to end up with many projects mixed everywhere.

It is a common practice in C# to group related projects inside a Solution folder to have them well organized.

This workflow can also be handled by the dotnet tool in this way:

Create a new Solution inside <SolutionName> folder to contain a group of related .NET projects
```
dotnet new sln --output <SolutionName>
```
Note: PascalCase (initial uppercase letters) is preferred for Solution names
Go inside the Solution folder
```
cd <SolutionName>
```
Verify that there is a .sln file (eg. using the ls command)
Create a new project inside <ProjectName> subfolder:
```
dotnet new console --output <ProjectName>
```
Also add the project to the .sln config:
```
dotnet sln add <ProjectName>
```
Note: this should be done for each project we want to create
Modify the project code as needed
Build and execute the project using the following command
```
dotnet run --project <ProjectName>
```
A project can also be removed from the Solution:
```
dotnet sln remove <ProjectName>
```
The remaining files should be removed by hand:
```
rm -rf <ProjectName>
```
Note: be careful with rm, deleted files will disappear forever! 😱

VSCode and .NET Solutions

This editor also has support for .NET Solutions if the correct extension is installed

Go inside the Solution folder and start a VSCode instance
```
cd <SolutionName>
code .
```
If VSCode asks about adding assets, just ignore the message!
- Note: the next section will show how to generate the assets for each specific project
Click the Extensions tab on the left toolbar
Look for the vscode-solution-explorer extension and install it
A new Solution tab should appear on the left toolbar
Click the Solution tab, a list of projects will be shown
Right-click any project in the list to see the context menu
Select SolutionExplorer: Run to build and execute that project
The context menues also allow other options:
- Add a new project
- Create a file (ie. class, interface, etc)
- Remove a project from the Solution
- etc ...

Run & Debug a single Project

To use Run & Debug features the easiest option is to open a single Project subfolder instead of a Solution folder.

Go inside a Project folder and start a VSCode instance
```
cd <SolutionName>/<ProjectName>
code .
```
If VSCode asks about adding assets, this time say yes and jump to step 6
- Note: this creates a .vscode subfolder with the required configurations
Otherwise open a .cs file to launch C# extension
Go to Run & Debug tab on the left toolbar
Click on Generate C# Assets for Build and Debug
- Note: this option only appears if .vscode assets were not created yet
Press F5 or the Start Debugging button in the Run & Debug tab
- Note: this step requires the assets to be already inside the .vscode subdirectory

Happy hacking! 🐱

Comments are not open for this post yet.

VSCode C# setup

2022-08-23T22:43:30-03:00

Posted on 2022-08-23 22:43:30 by rainbyte

Tags: c# dotnet vscode

Follow these steps to configure a C# development environment using VSCode (Code-OSS variant) with the Free OmniSharp extension.

This setup has been tested on Arch Linux with the following package versions:

code 1.70.2-1
dotnet-sdk 6.0.8.sdk108-1

Step-by-step procedure

Install dotnet sdk and runtime
- Arch Linux setup:
```
sudo pacman -S dotnet-sdk
```
Make a directory anywhere you like. Go inside and use dotnet tool to create a sample project with console template:
```
mkdir <ProjectName>
cd <ProjectName>
dotnet new console
```
Note: this folder can be deleted later, it is just an example to test if the extension is working
Open the editor inside the project folder
```
code .
```
Install free-omnisharp-vscode extension for C# development
Open Program.cs file
- Note: this step is just to force extension to download OmniSharp implementation
Wait until OmniSharp dependencies get installed (it takes time)
If editor asks about adding build & run targets, say yes
- It can also be enabled later inside Run & Debug tab
Press F5 to build and execute the example code
- Breakpoints are supported, add them to the left of the code
- Open Run & Debug tab to see variables and watch expressions
Now the editor is configured and new projects can be created using dotnet tool (like in step 2)

Happy hacking! 🐱

Comments are not open for this post yet.

The HTTP Language

2022-08-03T14:30:00-03:00

Posted on 2022-08-03 14:30:00 by rainbyte

Tags: api http request vscode

It is typical to see the situation where a developer has to work with services which provide an HTTP api.

Suppose we are implementing the following common endpoints:

GET /todos: list all the Todos
POST /todos: create a new Todo
PUT /todos/:id: update a Todo indicated by :id
DELETE /todos/:id: remove a Todo indicated by :id

After using a particular programming language to achieve the task, it is possible that we would like to communicate with it to test it works fine.

There are many tools in the market which allows us to make requests, even in a graphical point and click way, but I have found more confortable to have a text representation.

There is a file format called HTTP language which can represent requests in an standardized fashion and it is supported by CLI tools like httpYac and editor extensions like vscode-restclient.

The httpYac tool can be installed using npm with the following command:

npm -g install httpyac

I wrote a few examples about how to make requests to the proposed HTTP api using the HTTP language format. It can be seen in the following snippet that the syntax is very simple and complies with IETF request line spec.

HTTP language examples

We can obtain a single Todo using the GET verb followed by the host and the port where server is running, the HTTP version is optional:

GET http://localhost:4000/todos HTTP/1.1

To create a new Todo task we can follow the example and use POST verb, and in this case the Content-Type header should be specified, given that we are attaching a JSON data structure as body of the request:

POST http://localhost:4000/todos HTTP/1.1
Content-Type: application/json

{
    "text": "blabla",
    "completed": false
}

If we want to obtain a single Todo task then a variable could be used to indicate the :id, and the value can be accessed using brackets:

@get-todo-id = a0804e5f-a849-4920-9023-557ecdd790d1
GET http://localhost:4000/todos/{{get-todo-id}} HTTP/1.1

To modify a Todo task we use the PUT verb as appears on the proposed API. It is important to have the Content-Type header defined as we use JSON:

@put-todo-id = a0804e5f-a849-4920-9023-557ecdd790d1
PUT http://localhost:4000/todos/{{put-todo-id}} HTTP/1.1
Content-Type: application/json

{
    "text": "foobar",
    "completed": false
}

The format can also be used with the DELETE verb, and in this case we use a variable one more time, but with different name to avoid conflicts:

@del-todo-id = a0804e5f-a849-4920-9023-557ecdd790d1
DELETE http://localhost:4000/todos/{{del-todo-id}} HTTP/1.1

These snippets can be copied to a file with .rest or .http extension, eg. todo-requests.http, and executed this way:

httpyac todo-requests.http

Happy hacking! 🐱

Comments are not open for this post yet.

Clojure libraries and dependencies

2022-07-28T21:49:00-03:00

Posted on 2022-07-28 21:49:00 by rainbyte

Tags: clojure

The Clojure language provides some keywords to handle libraries in each file:

:require loads a Clojure library so it can be used in the current file or in the REPL
:use brings definitions to current namespace via aliases
:import gives access to native Java classes and interfaces

Note: in ClojureScript the native JavaScript code can be usually accessed using :require, but sometimes :import is needed (eg. for Google Closure library).

How to use these keywords

Load foo.bar and invoke a function from that library with the full namespace:

(ns user
  (:require
    [foo.bar]
    [foo.baz]))

(foo.bar/a-function)

Load a library making an alias to simplify access to a function:

(ns user
  (:require
    [foo.bar :as bar]
    [foo.baz :as baz]))

(bar/a-function)

Load with :refer only the definitions we are interested in:

(ns user
  (:require
    [foo.bar :refer [a-function]]))

(a-function)

Load with :refer only some definitions and also make aliases with :rename for our convenience:

(ns user
  (:require
    [foo.bar :refer [a-function]
             :rename [a-function func]]))

(func)

The :use keyword can be applied with :only to indicate which definitions will be provided:

(ns user
  (:use
    [foo.bar :only [a-function]]))

(a-function)

The :use keyword can also be applied without :only, but beware! It can cause conflicts, eg. the following snippet will have a problem if foo.bar and foo.baz namespaces provide definitions with the same name:

(ns user
  (:use
    [foo.bar]   ;; avoid :use without :only, it can cause conflicts!
    [foo.baz]))

(a-function)

Import a native Java class of java.util package and invoke the Date. method:

(ns user
  (:import
    (java.util Date)))

(Date.) ; call a Java method to get the current date

Comments are not open for this post yet.

Autenticación en GitHub usando SSH

2022-05-11T23:41:00-03:00

Posted on 2022-05-11 23:41:00 by rainbyte

Tags: git github ssh

Este post se muestra cómo autenticarse en GitHub mediante llaves SSH para poder interactuar con repositorios Git.

SSH (Secure SHell) es un protocolo que permite acceso remoto trabajando con pares de llaves (o claves) para generar canales seguros de comunicación.

El procedimiento es similar para otros proveedores de Git, como por ejemplo Bitbucket o GitLab.

Registrar una llave pública

A continuación se explica como generar un par de llaves, una privada que es secreta, y otra pública que se registrará en GitHub u otro proveedor Git:

Generar el par de llaves SSH reemplazando los campos <email> y <llave> con valores apropiados
```
ssh-keygen -t ed25519 -C <email> -f ~/.ssh/<llave>
```
Nota: el nombre id_ed25519_github podría ser adecuado para el campo <llave>, ya que el par de llaves se creó para GitHub usando el esquema ed25519.
Verificar que los archivos ~/.ssh/<llave> y ~/.ssh/<llave>.pub existen, siendo el de extensión .pub la llave pública (eso significa que puede mostrarse a 3ros sin preocupaciones)
Abrir el archivo ~/.ssh/config con un editor de texto, crearlo si no existe, y dependiendo del sistema operativo agregarle lo siguiente para cada caso:

Sistema Linux:
```
Host github.com
  IdentityFile ~/.ssh/<llave>
```
Sistema macOS:
```
Host github.com
  AddKeysToAgent yes
  UseKeychain    yes
  IdentityFile   ~/.ssh/<llave>
```
Agregar la llave privada para que el programa ssh-agent las recuerde

Sistema Linux:
```
ssh-add ~/.ssh/<llave>
```
Sistema macOS:
```
ssh-add -K ~/.ssh/<llave>
```
Agregar la llave pública a GitHub (esto debería ser similar para otros proveedores de repositorios Git)
1. Ir a Settings en el menú superior derecho
2. Abrir SSH and GPG keys en la columna izquierda
3. Clickear el botón New SSH Key
4. Llenar el campo Title a gusto con un nombre representativo
5. Ejecutar el comando cat ~/.ssh/<llave>.pub (¡atención! extensión .pub), copiar el resultado y pegarlo en el campo Key
6. Clickear el botón Save SSH Key

Repositorios locales

Al abrir un repositorio en GitHub se puede obtener la url para clonarlo, para ello debe hacerse click en el botón verde que dice Code ▼, y luego abrir la pestaña SSH.

Una dirección url SSH tiene la forma git@github.com:<usuario>/<repositorio>.git, y ese repositorio remoto puede clonarse de la siguiente manera:

git clone <url>

En caso de tener un repositorio previamente clonado desde un remoto llamado origin (es lo habitual), es posible cambiar su url así:

git remote set-url origin <url>

En ambos casos, y asumiendo que el remoto se llama origin, se puede verificar la url del mismo con este comando:

git remote get-url origin <url>

Comments are not open for this post yet.

Android folder backup via Rsync

2022-05-01T23:41:00-03:00

Posted on 2022-05-01 23:41:00 by rainbyte

Tags: android backup rsync

This post describes how to backup a folder from an Android phone to a PC and restore it on a 2nd phone.

Backup procedure

Download simplesshd on the 1st phone (play store link)
Open simplesshd and click start. The log will show some relevant information:
- host: something like ip 192.168.x.y
- port: default is 2222
Run rsync backup command on the PC. Replace <host> and <port> with the correct values for 1st phone!
```
rsync -auv --delete -e 'ssh -p <port>' <host>:'/sdcard/orig-dir/' '/path/to/backup-dir/'
```
- Rsync will copy files from 1st phone orig-dir folder to PC backup-dir folder
- delete removes from PC folder the files not in the 1st phone
- Note: final / on each folder are required!

Restore procedure

Download simplesshd on the 2nd phone (play store link)
Open simplesshd and click start. The log will show some relevant information:
- host: something like ip 192.168.x.y
- port: default is 2222
Run rsync restore command on the PC. Replace <host> and <port> with the correct values for 2nd phone!
```
rsync -uv --omit-dir-times --no-perms --recursive --inplace --delete -e 'ssh -p <port>' '/path/to/backup-dir/' <host>:'/sdcard/dest-dir/'
```
- Rsync will copy files from PC backup-dir folder to 2nd phone dest-dir folder
- inplace avoids double sdcard write (caused by copy and rename)
- no-perms is useful when perms are not supported, eg.: mtp mounts
- omit-dir-times ignores timestamps
- delete removes from 2nd phone folder the files not in the PC folder
- Note: final / on each folder are required!

Comments are not open for this post yet.

Haskell from 0 to IO (Maybe Hero)

2020-08-28T03:56:00-03:00

Posted on 2020-08-28 03:56:00 by rainbyte

Tags: haskell io monad typeclasses

Introduction

This guide references some syntax and patterns used when writing programs in the Haskell language. A text editor and the GHC compiler are required to run the code, but online environments are also an option.

Minimal example

Haskell expects programs have an entrypoint called main, which later is explained in detail, but for now we will create a file named Program.hs and write inside the following code:

-- Comments are written like this
main = print "hola"

Check if code can be interpreted:

runghc Program.hs

Check if code can be compiled and executed:

ghc -o Program Program.hs
./Program

Some system also require to add the -dynamic option (eg. Arch Linux).

Definitions

Haskell definitions indicate a type with :: and their value with =.

Here num is defined with type Int and value 9:

num :: Int -- type
num = 9    -- definition

main = print num

The = symbol means equality in both ways, this means that num can be replaced by 9 anywhere.

Detailed definitions are done using let..in.., which has a let section with local values accessed by the in section to calculate a final value.

num =
    let x = 5  -- define x
        y = 10 -- define y
    in x + y   -- use them

main = print num

Other way to have local definitions is to attach a where section, the following code is equivalent to the previous one:

num = x + y -- use definitions
  where
    x = 5  -- define x
    y = 10 -- define y

main = print num

Types

Carefully designed types reject unwanted values by making them unrepresentable.

The type keyword indicates an alias to an existing type.

Here String is an alias to a list of Char:

type String = [Char]

The data keyword is used to define custom types.

Booleans are represented in this way:

data Bool = False | True

We can apply conditionals over booleans like this:

b :: Bool
b = True

s :: String
s = if b then "True" else "False"

main = print s

The Ordering type is used to compare things:

data Ordering = LT | EQ | GT

Handling each possible case for a type is called pattern matching, and ideally all of them should be handled

ord :: Ordering
ord = LT

s :: String
s = case ord of
    LT -> "Less Than"
    EQ -> "Equal"
    GT -> "Greater Than"

main = print s

The Maybe type is parametrized and represents the existence of something with a generic type t, avoiding the use of null at all.

data Maybe t = Nothing | Just t

Pattern matching also works with parametrized types:

mInt :: Maybe Int
mInt = Just 9

num :: Int
num = case mInt of
    Just n  -> n
    Nothing -> 0

main = print num

The Either type has 2 parameters and represents the existence of a value with type e or a value with type t.

data Either e t = Left e | Right t

We can use Either String t to represent an error message when a result of type t cannot be obtained.

err :: Either String Int
err = Left "Could not obtain the number"

Functions

When we see an arrow -> in a type, we know it is a function.

Every function receives an a and gives a b as result.

f :: a -> b

Functions indicate their body with =.

f :: Int -> Int
f x = x + 3

main = print (f 5)

The same function can be implemented inline as a lambda

f :: Int -> Int
f = \x -> x + 3

main = print (f 5)

We can "combine" functions using the . operator, called composition, so that if we have g . f then f will produce an intermediate result to be taken by g to produce a final result:

f :: Int -> Int
f x = x + 3

g :: Int -> Int
g x = x * 5

h :: Int -> Int
h = g . f -- be careful with the order

main = print (h 2)

There is also an $ operator, called "application", usually used to change precedence and avoid extra parenthesis. You can think of it as having parenthesis at both sides.

Here we have equivalent main implementations, choose the one you prefer.

f :: Int -> Int
f x = x + 1

-- all of these are equivalent
main1 = print . f $ 3 + 4
main2 = (print . f) $ (3 + 4)
main3 = (print . f) (3 + 4)
main4 = print (f (3 + 4))

main = main1

A function can give a function as result and we can use this mechanism to make new definitions:

f :: Int -> (Int -> Int)
f x = \y -> x + y

add5 = f 5

main = print (add5 6)

Parenthesis in that type signature can be omitted, and we can also evaluate the f function with all the parameters at once:

f :: Int -> Int -> Int
f x = \y -> x + y

main = print (f 5 6)

We can also move the y parameter to the left side, just to make it easier to read:

f :: Int -> Int -> Int
f x y = x + y

main = print (f 5 6)

A function can receive a function as parameter, but then those parenthesis are required to maintain precedence. We don't know what the h function does, but we know it can be used over an Int like 3.

g :: (Int -> Int) -> Int
g h = h 3

f x = x + 2

main = print (g f) -- g consumes f function

Pattern matching can also be used to define a function piece-by-piece

fib :: Int -> Int
fib 0 = 0
fib 1 = 1
fib x = fib (x - 1) + fib (x - 2)

main = print (fib 10)

Typeclasses

When types are generic, function body can only use known operations.

Here type a could be any type, so x can only be returned as-is.

id' :: a -> a
id' x = x

main = print (id' 5)

We can define a set of operations, then types could implement them, that is called typeclass.

As example a type which fulfils the Eq typeclass will have all its functions available.

class Eq a where
    (==) :: a -> a -> Bool
    (/=) :: a -> a -> Bool
    (/=) x y = not (x == y)

We can see that Ord needs b to implement Eq, because it needs operations from that set.

class Eq b => Ord b where
    compare              :: b -> b -> Ordering
    (<), (<=), (>=), (>) :: b -> b -> Bool
    max, min             :: b -> b -> b

Typeclass implementation is done via instances for each type.

Here we define Eq for the Bool type.

Remember that (/=) is already defined based on (==).

instance Eq Bool where
    (==) True  True  = True
    (==) False False = True
    (==) _     _     = False

The type t implements Ord and Num typeclasses, so inside isPositive we can use number and comparison operations over x value.

isPositive :: (Ord t, Num t) => t -> Bool
isPositive x = compare 0 x

Input/Output

Now we are ready to inspect the type of the main function we wrote at the beginning.

main :: IO ()
main = print "hola"

The IO a type represents a set of instructions that will be executed by the runtime of Haskell, with something of type a as result.

In the case of main a is (), which is called unit, and its only possible value is ().

This means that the main function produces a set of instructions to be executed by the runtime when the program is launched.

We know that print "hola" type is also IO () because it should have the same type that main has to be valid code, and we also know that "hola" is a String.

We could think that print :: String -> IO (), but we have been using print with things of other types too, so its type should be something like C a => a -> IO () with some unknown constraint C.

That constraint is the Show typeclass we can see here:

class Show a where
    show :: a -> String
    -- plus other definitions

Given that show function takes something and produces a String, then that function is the missing piece.

Then we can infer that print type is Show a => a -> IO (), so a is converted to an String which is printed.

This is the definition of the print function:

print :: Show a => a -> IO ()
print x = putStrLn (show x)

As we can see, it uses show to obtain an String, which will be consumed by the putStrLn function, and that is the one that has the String -> IO () type we thought before.

We will see soon how to write bigger programs using IO a type, but first we should talk a bit more about typeclasses.

Typeclass Laws

Some typeclasses define a set of associated laws which cannot be checked by the compiler, but the code must follow them to preserve the logic.

Haskell relies on developers to check that their code adheres to the laws, which could be done via mathematical proofs, but there are also tools to generate informal tests to check properties (eg. QuickCheck).

We can take as example the Eq typeclass we saw before:

class Eq a where
    (==) :: a -> a -> Bool
    (/=) :: a -> a -> Bool

A valid Eq implementation should follow these laws:

Reflexivity: x == x = True
Symmetry: x == y = y == x
Transitivity: if x == y && y == z = True, then x == z = True
Substitution: if x == y = True, then f x == f y = True
Negation: x /= y = not (x == y)

We can see that our previous Eq Bool instance follows reflexivity law, because by definition agrees with x == x form:

(==) True  True  = True
(==) False False = True

Given that our implementation is valid, we can always replace x == x with True when we see it, which is useful to simplify our code.

Typeclass laws help us to refactor the code and make it better using known properties.

Typeclass Examples

There are many typeclasses defined in the Haskell libraries, the Typeclassopedia is a good place to start learning more details about the standard typeclasses, but I will mention here some of the most common ones and their laws, just as reference, there is no need to memorize them now because they will become familiar as time passes.

Semigroup Typeclass

Types which fulfil Semigroup api should implement (<>) function, also called append.
```
class Semigroup a where
    (<>) :: a -> a -> a
    -- other definitions...
```
The following property, called associativity, should be true for any valid Semigroup instance:
- (x <> y) <> z = x <> (y <> z)
We can use (<>) function to take to things of the same type and produce a combined result also of the same type.
```
s1 = "hola"
s2 = "mundo"

main = print (s1 <> s2)
```
Each Semigroup instance defines how those things are combined, in this case String concatenation occurs.
Functor Typeclass

Types which fulfil Functor api implement fmap function.
```
class Functor t where
    fmap :: (a -> b) -> t a -> t b
    -- other definitions...
```
The following properties should be true for any valid Functor instance:
- fmap id == id
- fmap (f . g) == fmap f . fmap g
We can use fmap over a parametrized type t a to apply a function a -> b which takes things of type a to produce things of type b.

Here fmap is applied over a parametrized List Int to apply f function which will add 3 to each integer inside the list, obtaining a new list with the same shape but new values.
```
xs :: [Int]
xs = [1, 2, 3]

f :: Int -> Int
f x = x + 3

main = print (fmap f xs)
```
Remember, fmap behavior depends on the specific parametrized type we are working with, eg. in the case of data structures usually allows us to apply a function over each element preserving the structure shape.
Applicative Typeclass

Types which fulfil Applicative api should implement the required functions (ie. pure, (<*>), etc) and must have a Functor instance as well, so the fmap function will be available as well.
```
class Functor t => Applicative t where
    pure :: a -> t a
    (<*>) :: t (a -> b) -> t a -> t b
    -- other definitions...
```
The following properties should be true for any Applicative instance:
- pure id <*> v = v
- pure (.) <*> u <*> v <*> w = u <*> (v <*> w)
- pure f <*> pure x = pure (f x)
- u <*> pure y = pure ($ y) <*> u
The pure function is really useful when working with a parametrized type t a (eg. IO a, Maybe a, etc) because it allows us to take something of type a and generate a value of type t a in a predefined way.
```
main = pure ()
```
This example shows a program which does nothing, but it is interesting anyway because we can see how pure obtains a IO a from an a, which in this case is the unit type.
Monad Typeclass

Any type which implements Monad will have a (>>=) operation, called bind, it should also implement Applicative and Functor api as well, so we also have the pure and fmap functions available for Monad instances.
```
class Applicative m => Monad m where
    (>>=) :: m a -> (a -> m b) -> m b
    -- other definitions...
```
When we see mf >>= k we know k consumes something of type a obtained from mf (because mf :: m a and k :: (a -> m b)), so we can say k is a continuation, because it could be the next piece to be executed.

Keep in mind that the following properties are required for any valid Monad instance:
- pure a >>= k = k a
- mf >>= pure = mf
- mf >>= (\x -> k x >>= h) = (mf >>= k) >>= h
The >>= function is useful when we have something of a parametrized type t a and we want to process the values of type a with the condition that in the end we should produce something of type t b.
```
f :: Int -> String
f n = "n = " <> show n

mInt :: Maybe Int
mInt = Nothing

main = print (mInt >>= (pure . f))
```
In the example we have mInt of type Maybe Int and we would like to process that Int with the function f to obtain an String, so we use the bind function >>= to do handle this and give pure . f as continuation, so it conforms with the expected type Int -> Maybe String.

The parametrized type Maybe a has a bind implementation which is intelligent enough to note that the a (ie. Int) doesn't exist, because mInt value is Nothing, so bind avoids calling pure . f as the continuation expects the Int to be there.

We can se that pure . f uses pure to conform with Int -> Maybe Int type, and it could have consumed an Int if mInt had it (eg. mInt = Just 4).

As we can see, bind mechanism and meaning are related to the parametrized type which implements the Monad instance, so we need to understand that type very well before learning about the inner working of a certain typeclass instance.

Do-notation

Finally, as promised, we can see how to write bigger programs using IO a type.

First we can see a piece of code which uses (>>=) operator to obtain a String written by the user and then prints it to the console.

main = getLine >>= putStrLn

We can rewrite it using an explicit parameter named line, which is produced by getLine subroutine and passed to the continuation (remember that when we see something like mf >>= k, then k is the continuation).

main = getLine >>= (\line -> putStrLn line)

As this gets tiring really quickly, Haskell defines a special syntax called do-notation, which we can use to write equivalent code in a more familiar style.

Like in 2nd example getLine result is available as line value.

main = do
    line <- getLine
    putStrLn line

As a final example we have an imperative-style program which asks the user for an input and then iterates over the elements of a list printing the user input each time.

import Control.Monad (forM_)

xs = [1..10]

main = do
    line <- getLine
    forM_ xs $ \x -> do
        putStrLn (line <> show x)

There are other ways to write this program, but this can feel familiar to programmers which already know other languages.

Using Kotlin coroutines to handle blocking computations in Android

2020-05-18T05:23:00-03:00

Posted on 2020-05-18 05:23:00 by rainbyte

Tags: android async coroutines kotlin

When we need to execute time intensive computations and show some the result to the user, we should avoid running them inside UI thread, otherwise app UI could get frozen.

Here we have a detailed example which uses a coroutine to run Fibonacci fib function without blocking app UI:

class MainActivity : AppCompatActivity(), CoroutineScope {

    // Blocking computation, requires too much time to finish
    fun fib(x: Int): Int = if (x <= 1) x else fib(x - 1) + fib(x - 2)

    // Attach coroutines context to activity
    override val coroutineContext: CoroutineContext =
            Dispatchers.Main + SupervisorJob()

    // Coroutines should respect activity lifetime
    override fun onDestroy() {
        super.onDestroy()
        coroutineContext[Job]!!.cancel()
    }

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)

        btnCalc.setOnClickListener {
            val number: Int = editNumber.text.toString().toInt()
            // Start coroutine on the context attached to activity
            this.launch {
                // Switch to IO dispatcher to perform blocking computation
                val result = withContext(Dispatchers.IO) {
                    fib(number)
                }
                if (result != null) {
                    editResult.setText(result.toString())
                }
            }
        }
    }
}

UI code is also provided to complete the example

<?xml version="1.0" encoding="utf-8"?>
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    android:orientation="vertical"
    android:layout_margin="10dp"
    tools:context=".MainActivity">

    <TextView
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:text="Number" />

    <EditText
        android:id="@+id/editNumber"
        android:layout_width="match_parent"
        android:layout_height="wrap_content" />

    <TextView
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:text="Result" />

    <EditText
        android:id="@+id/editResult"
        android:layout_width="match_parent"
        android:layout_height="wrap_content" />

    <Button
        android:id="@+id/btnCalc"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:text="Calculate fib(number)" />

</LinearLayout>

Plantillas de Gnome

2019-12-07T02:51:00-03:00

Posted on 2019-12-07 02:51:00 by rainbyte

Tags: gnome

Plantillas de Gnome

Gnome posee una carpeta ~/Plantillas en la cual es posible agregar archivos como base para crear nuevos documentos de forma automática.

Muchas veces se da el caso de crear documentos con cierto contenido que se repite en cada uno de ellos, por ejemplo los archivos .desktop:

[Desktop Entry]

Type=Application
Name=Firefox
Exec=/usr/bin/firefox

Como puede verse, estos documentos siempre tienen la misma cabecera y algunas opciones que deben estar allí siempre (ej. Type y Name).

Como solución podríamos crear un archivo ~/Plantillas/Nuevo Desktop Entry.desktop, para evitar tipear esas cosas, algo asi:

[Desktop Entry]

Type=Application
Name=${nombre}
Exec=${comando}

Luego desde Nautilus podemos hacer click derecho e ir al menú Nuevo documento... y allí ver nuestra plantilla.

Finalmente es cuestión de cambiar el nombre y rellenar los campos (ej. ${nombre} y ${comando}).

Pandoc filter for custom ruby notation

2018-11-22T03:12:00-03:00

Posted on 2018-11-22 03:12:00 by rainbyte

Tags: blog haskell pandoc markdown chinese japanese

The motivation

Chinese and Japanese languages use ideograms in their written forms, but sometimes it is useful to show the reader how those ideograms should be pronounced. To do that, phonetic systems like {汉语|hànyǔ}{拼音|pīnyīn} and {振り仮名|fu|ri|ga|na} are used.

In html documents we can use ruby elements to show phonetic representation above the ideograms, like in the following example:

Code	Expected Result
`我喜欢<ruby>汉<rt>hàn</rt>字<rt>zì</rt></ruby>`	中国汉hàn字zì

The problem is that writing text using ruby elements it is tedious and error prone. We prefer writing something like the following examples:

Code	Expected Result
`我喜欢{汉字	hàn
`我喜欢{汉字	hànzì}`
`我喜欢{汉字	}`
`我喜欢{汉字	hà
`我喜欢{汉字}`	我喜欢{汉字}
`我喜欢{	hànzì}`
`我喜欢{	}`

The rest of the post explains how to handle those custom markdown expressions to produce the ruby elements without writing them by hand. I implemented this code in Haskell language as a Pandoc filter, because this blog uses Hakyll static generator which uses the Pandoc library.

Document representation

Pandoc uses a custom datatype to represent in an uniform way the multiple types of contents it can handle. That type is called Pandoc and basically contains a tree-like structure formed by different nodes. We are interested in processing only nodes which are specific instances of the Inline type, because they contain the pieces of text we want to modify.

We have a piece of code which process the provided Pandoc data structure.

transformCustomMarkdownRuby :: Pandoc -> Pandoc
transformCustomMarkdownRuby = walk handleInline
  where
    handleInline :: Inline -> Inline
    handleInline (Str s) = case (parse markdownRuby "" s) of
        (Left _)     -> Str s
        (Right rubies) -> RawInline (Format "html") (rubiesToHtml rubies)
    handleInline x       = x

The key point in this code is the pattern matching over the Inline type, specifically over the Str instances. We use the walk function to process all the matched nodes recursively, leaving the other ones untouched. A RawInline instance is generated when ruby tags are found, otherwise the original Str instance is preserved.

Text processing

When we have a candidate to be modified, it is necessary to verify if it follows the correct syntax, so we can parse it to extract the data and render it the way we want.

Now, here we have the code which does main work:

markdownRuby :: Parsec String () [(String,[(String,String)],String)]
markdownRuby = many $ choice [try ruby, fallback]
  where
    ruby :: Parsec String () (String,[(String,String)],String)
    ruby = (,,) -- (openingText,rubyPairs,closingText)
        <$> (many $ noneOf "{")
        <*> between (char '{') (char '}') markdownRubyPairs
        <*> (many $ noneOf "{")
    fallback :: Parsec String () (String,[(String,String)],String)
    fallback = (,,) -- (openingText,rubyPairs,closingText)
        <$> (many1 $ anyChar)
        <*> pure []
        <*> pure ""
markdownRubyPairs :: Parsec String () [(String,String)]
markdownRubyPairs = do
    elems <- taggedElems
    tags  <- many1 rubyTag
    let sameLen = length elems == length tags
        matchingPairs = zip elems tags
        singlePair = [(mconcat elems,intercalate "|" tags)]
    pure $ if sameLen then matchingPairs else singlePair
  where
    taggedElems :: Parsec String () [String]
    taggedElems = fmap (fmap pure) (many (noneOf "|}"))
    rubyTag = char '|' *> (many $ noneOf "|}")
rubyToHtml :: (String,[(String,String)],String) -> String
rubyToHtml (prev,pairs,next) = prev <> pairsToHtml pairs <> next 
  where
    pairsToHtml [] = ""
    pairsToHtml ps = (wrap . mconcat . fmap pairToHtml) ps
    pairToHtml ("","") = ""
    pairToHtml (elem,tag) = elem <> "<rt>" <> tag <> "</rt>"
    wrap x = "<ruby>" <> x <> "</ruby>"
rubiesToHtml :: [(String,[(String,String)],String)] -> String
rubiesToHtml = mconcat . fmap rubyToHtml

We are using a library called Parsec, which provides us tools to easily handle the parsing. This code uses them to separate the text in 3 parts: the text before our target, the target itself, the text after our target. Because our target should be between braces, we use te between combinator to find it.

When the target is found, its contents are separated into base elements and their respective ruby tags, so they can be grouped into pairs. It is assumed that the number of elements and tags is equal, otherwise we have to merge them into a single pair to preserve this property.

Finally, when we have the independent pieces, we can take and arrange them to render the view in the format we like. Pandoc support many formats, but in this case we are using Html.

Some caveats

The current code doesn't handle some cases well. I'm still working on it to make it work with markdown tables, formatting inside the tags, and other missing bits.

Use GitHub API to implement comments feature

2018-11-16T22:48:00-03:00

Posted on 2018-11-16 22:48:00 by rainbyte

Tags: blog

The comments section of this blog is implemented via standard GitHub issues and given that GitHub provides an API to access the public information of a repository, we can use it. If we have a repository with issues already created, we can access the comments of a certain issue using an URL like this one:

https://api.github.com/repos/${username}/${repository}/issues/${issueId}/comments

Using that endpoint the API provides us the comments as a list of Javascript objects, each one being similar to this:

{
    "body": "comment text",
    "created_at": "when was the comment published",
    "user: {
        "avatar_url": "user image location",
        "html_url": "user profile location",
        "login": "user nickname"
    }
}

Of course there are much more fields available, but these ones are representative enough and using them we can write some Javascript code to render the comments HTML view. This is the code used in this blog to render comments below:

var issueId = $commentsIssue$;
var url = "https://github.com/rainbyte/rainbyte.github.io/issues/" + issueId;
var api_url = "https://api.github.com/repos/rainbyte/rainbyte.github.io/issues/" + issueId + "/comments";
(function() {
    // DOM is already available, now we can handle page elements
    var ghCommentsList = document.getElementById("gh-comments-list");

    var request = new XMLHttpRequest();
    request.open('GET', api_url, true);
    request.onload = function() {
        if (request.status >= 200 && request.status < 400) {
            // Request was successful, we can process the raw comments
            var comments = JSON.parse(request.responseText);
            var fragment = document.createDocumentFragment();
            var range = new Range();

            // Render comments section header
            fragment.appendChild(range.createContextualFragment(`
                <div>
                    <b>Comments section</b> (visit the <b><a href='${url}'>issue</a></b> of this post to add one)
                </div>
            `));

            // Render view of each comment
            comments.forEach(comment => {
                var date = new Date(comment.created_at);
                var renderedComment = range.createContextualFragment(`
                    <div class='gh-comment'>
                        <div class='gh-comment-header'>
                            <img src='$${comment.user.avatar_url}'>
                            <div>
                                <b><a href='${comment.user.html_url}'>${comment.user.login}</a></b> posted at <em>${date.toDateString()}</em>
                            </div>
                        </div>
                        <div class='gh-comment-body'>
                            $${comment.body}
                        </div>
                    </div>
                `);
                fragment.appendChild(renderedComment);
            });

            // Make changes visible by adding rendered nodes
            ghCommentsList.append(fragment);
        } else {
            // Request reached the target server, but it returned an error
            ghCommentsList.append("Comments are not available now.");
        }
    };
    request.onerror = function() {
        // There was a connection error of some sort
        ghCommentsList.append("Comments are not available now.");
    };
    request.send();
})();

If code is working ok, you can see a comments section under this text and add a new comment following the provided link.

Set terminal tab title using fish shell

2018-11-12T07:28:00-03:00

Posted on 2018-11-12 07:28:00 by rainbyte

Tags: fish shell

Approach #1: setting the title by hand

When there are many terminal tabs opened, it is really useful to give them meaninful names.

Fish shell allows setting the current tab's title creating a fish_title function.

If we want to name our tab FOO, we could just write this in the terminal:

function fish_title
    echo "FOO"
end

After entering the code, the function will be exported and the new title will be used.

The problem with this way is that writing the function each time is tedious.

There is an easy way to overcome this problem.

Approach #2: using a helper function

We could write a helper which export the fish_title function for us.

I call this helper set_title, but other name could be used as well.

First we need to write the helper function:

function set_title
    set -l title $argv[1]
    function fish_title --inherit-variable title
        echo "$title"
    end
end

Now we can test it, eg. to name our tab BAR we could call it this way: set_title BAR

Finally, to save the function persistently, we execute this: funcsave set_title

How does it work?

Each time we execute set_title, it will re-export the fish_title function.

We need to make the title variable available inside fish_title scope.

The trick is using the --inherit-variable option, which will solve this for us.

Comments are not open for this post yet.

Programación de GPU en Haskell usando GPipe - Parte 2

2016-10-26T07:29:00-03:00

Posted on 2016-10-26 07:29:00 by rainbyte

Tags: gpipe gpu haskell opengl

Nota: estas leyendo la traducción al castellano de una serie de tutoriales en ingles sobre GPipe; la versión original, escrita por Tobias Bexelius (creador de GPipe), se encuentra aqui.

< Episodio previo: Hello triangle

¡Bienvenido nuevamente! En la ultima parte obtuviste tu primer triangulo mediante GPipe. Esta vez vamos a examinar Buffer y PrimitiveArray con más detalle.

Buffers

En el ejemplo "Hello world" que hicimos la ultima vez, usamos un Buffer para almacenar las posiciones y colores del triangulo. A partir de este buffer, creamos un PrimitiveArray que enviamos al shader. Más adelante vamos a ver que un Buffer puede ser usado también para otras cosas.

Un Buffer en GPipe es un array de datos que esta almacenado en la GPU. Es mutable, así como IOArray o STArray, y así como aquellos también vive en una monada, en este caso la monada ContextT. Veamos primero la función que se encarga de crear buffers:

newBuffer :: (MonadIO m, BufferFormat b) => Int -> ContextT w os f m (Buffer os b)

Un buffer tiene tipo Buffer os b, donde os es el mismo que el de ContextT. Como puedes recordar desde la ultima vez, este parámetro de tipo os es usado para evitar que los objetos asociados a un contexto puedan escapar de la monada, y Buffer es uno de esos objetos.

newBuffer solo toma un argumento: el numero de elementos a crear en el buffer. Un buffer tiene elementos mutables, pero el numero de elementos es inmutable. El tipo de los elementos del buffer se denota con b, y puedes ver que este b esta delimitado por el typeclass BufferFormat b. Antes de mostrarte ese typeclass, miremos la función que vas a usar para llenar el buffer con datos desde el lado de la CPU:

writeBuffer :: MonadIO m => Buffer os b -> BufferStartPos -> [HostFormat b] -> ContextT w os f m ()

Esta función toma un buffer para escribir y una posición de inicio con indice basado en cero, nada extraño en esto, pero luego toma una lista de HostFormat b... ¿Que ocurre con esto? Los contenidos de un buffer no tienen la misma representación en el host que en el buffer, el cual vive en la GPU (desde ahora voy a usar el termino host cuando me refiero al entorno normal de Haskell que vive en la CPU, en contraposición al mundo de la GPU). HostFormat b es un tipo al typeclass BufferFormat b. Miremos ese typeclass:

class BufferFormat f where
  type HostFormat f
  toBuffer :: ToBuffer (HostFormat f) f

El único propósito de esta clase, es proveer una representación para el tipo de los elementos del buffer en el host, así como una conversión de la representación del host a la del buffer. Aquí hay algunos ejemplos de instancias de esta clase, y sus representaciones en el host:

f	HostFormat f
B Float	Float
B Int32	Int32
B Word32	Word32
B2 Float	V2 Float
B2 Int32	V2 Int32
B2 Word32	V2 Word32
B2 Int16	V2 Int16
B2 Word16	V2 Word16
(a, b)	(HostFormat a, HostFormat b)
V2 a	V2 (HostFormat a)

Hay muchas más instancias, incluyendo B3, B4 y tuplas mas grandes. Mira la lista completa en hackage.

Un Float en el host se convertirá B Float en el Buffer. B a es un tipo opaco de cual no puedes inspeccionar su valor o hacer ningún calculo, por ej. no hay instancia de Num para B Float. Para Buffer no se expone una manera de aplicar funciones en sus elementos de ninguna manera (por ej. Buffer no posee instancia del typeclass Functor), pero vamos a crear pronto un VertexArray a partir de nuestro Buffer y entonces será distinto.

GPipe también define los tipos B2 a, B3 a y B4 a. Para un conjunto selecto de a, B2 a es la representación en el buffer de un V2 a en el host. V2 a es también una instancia de BufferFormat con V2 (HostFormat a) como representación en el host, lo cual significa que tanto V2 (B Float) como B2 Float tienen la misma representación en el host: V2 Float. Ambos formatos de buffer tienen el mismo tamaño e incluso disposición interna, pero B2 Float puede ser usado de manera más eficiente como vamos a ver luego. Por esta razón, siempre intenta usar tipos B en vez de tipos V en los buffers, cuando sea posible. Entonces, ¿porque hay una instancia de BufferFormat para V2? El caso de uso principal es el de las matrices, por ej. V4 (V4 Float) en el host puede almacenarse en un buffer como V4 (B4 Float).

Otra cosa interesante que puedes haber notado al estudiar la lista de instancias de BufferFormat, es que hay instancias de B2 Int16 y B2 Word16, pero no de B Int16 ni B Word16. Esto es porque los atributos de los vértices tienen que estar alineados a 4 bytes en algunas piezas de hardware, y GPipe respeta esto en sus tipos de datos. Int16 y Word16 son ambos de 2 bytes, así que necesitas tener un vector de al menos dos de ellos. Hay instancias de B3 Int16 y B3 Word16, pero estas poseen un relleno (padding) de 2 bytes extra. La motivación para esto es que siempre podrías usar B Int32 en vez de B Int16 si existiese, funcionarían con los mismos shaders y serian del mismo tamaño de todas formas si agregamos el relleno para el segundo. Por otra parte, un B3 Int32 toma 12 bytes mientras que un B3 Int16 con relleno incluido solo ocupa 8 bytes, así que hay un caso distintivo para este ultimo. Un B4 Int16 también utiliza 8 bytes, pero no funcionaria con los mismos shaders, como va a ser evidente en la siguiente parte de este tutorial.

Ahora miremos el miembro toBuffer del typeclass BufferFormat. Posee el tipo ToBuffer (HostFormat f) f. ToBuffer es algo llamado arrow en Haskell. Es como una función (en este caso HostFormat f -> f), pero más general. Echemos un vistazo a la instancia BufferFormat (a, b) como ejemplo:

{-# LANGUAGE Arrows #-}

instance (BufferFormat a, BufferFormat b) => BufferFormat (a, b) where
  type HostFormat (a,b) = (HostFormat a, HostFormat b)
  toBuffer = proc ~(a, b) -> do
                a' <- toBuffer -< a
                b' <- toBuffer -< b
                returnA -< (a', b')

La notación arrow casi se parece a un lambda (usando el keyword especial proc) retornando una acción monadica. Pero no es una monada. La mayor diferencia con una monada es que no puede seleccionar una acción basándose en los valores de retorno del arrow. Es por esto que las acciones de un arrow poseen una cola (-<); cualquier cosa entre las partes <- y -< de un arrow, no puede referenciar nada fuera de ellas (a, b, a', b' en este caso). Esto obliga a que toda invocación a toBuffer deba ir a través de la misma serie de acciones de arrow, independientemente de los valores de entrada reales. Otro requerimiento adicional que tiene GPipe, es que necesita ser capaz de producir valores de forma lazy, es por ello el tilde (~) en el patrón proc. Las únicas acciones del arrow ToBuffer que GPipe define para usar en tu propia implementación de toBuffer, son los métodos toBuffer de otras instancias. Vas a ver aparecer este patrón, donde un arrow es usado para definir la conversión entre dos dominios, en varios lugares de GPipe a medida continuemos con el tutorial.

Arrays de vértices

Bueno, ¡ahora eres un experto en buffers! Vamos a darles algún uso:

newVertexArray :: Buffer os a -> Render os f (VertexArray t a)

Ejecutas esta función en una monada Render para crear un VertexArray t a. Un array de vértices es como la vista de un buffer, y newVertexArray no copia ningún dato. Ya que operamos dentro de la monada Render (que es ejecutada por la función render, la cual no permite valores de retorno), y un Buffer solo puede ser modificado fuera de esta monada (en la monada ContextT), conceptualmente podrías pensar a VertexArray como una copia del Buffer. No lo es realmente, pero puedes tratarlo como una.

VertexArray t a es un array de vértices donde cada vértice es un elemento de tipo a, que es el mismo tipo de los elementos del Buffer a partir del cual lo creaste. No te preocupes por el parámetro T por ahora, vamos a llegar a eso en un momento. El VertexArray posee tantos vértices como elementos pertenecientes al Buffer que lo origina, pero en contraste a este ultimo, puedes recortar un VertexArray usando las funciones dropVertices o takeVertices. Estas funcionan exactamente como drop o take trabajan sobre listas normales:

takeVertices :: Int -> VertexArray t a -> VertexArray t a Source
dropVertices :: Int -> VertexArray () a -> VertexArray t a Source

VertexArray también tiene una instancia de Functor, la cual permite aplicar fmap sobre los vértices. ¡Aqui es donde la opacidad de los tipos B entran en juego! Ahora que puedes hacer cosas con tus valores B, vas a notar que las opciones son algo limitadas. Puedes simplemente agarrar elementos de estructuras como tuplas y/o construir nuevas estructuras con los valores que posees. A pesar de esto, hay un par de funciones que operan sobre valores B que puedes usar aquí:

toB22 :: forall a. (Storable a, BufferFormat (B2 a)) => B4 a -> (B2 a, B2 a)
toB3 :: forall a. (Storable a, BufferFormat (B3 a)) => B4 a -> B3 a
toB21 :: forall a. (Storable a, BufferFormat (B a)) => B3 a -> (B2 a, B a)
toB12 :: forall a. (Storable a, BufferFormat (B a)) => B3 a -> (B a, B2 a)
toB11 :: forall a. (Storable a, BufferFormat (B a)) => B2 a -> (B a, B a)

Estas permiten separar vectores B en partes mas pequeñas. Fijate que de todos modos no hay funciones que puedan combinarlas nuevamente.

Puedes también hacer comprimir (zip) dos VertexArray juntos, con la función zipVertices, que funciona exactamente como zipWith para listas normales; provees una función para combinar los elementos de ambos argumentos VertexArray y el resultante sera del tamaño del más pequeño de ambos arrays:

zipVertices :: (a -> b -> c) -> VertexArray t a -> VertexArray t' b -> VertexArray (Combine t t') c

(Nuevamente, no te preocupes por el extraño primer parámetro en el VertexArray retornado, lo explicaré más adelante)

Comprimir arrays de vértices es lo que se corresponde con usar arrays no-intercalados (non-interleaved) en OpenGL, mientras que un array de vértices desde un solo buffer de un tipo de elementos compuestos (así como una tupla de dos valores B) corresponde a arrays intercalados (interleaved). ¡Esta es solo la manera funcional y type safe de hacerlo!

Arrays de primitivas

Ahora que haz recortado (trim), comprimido (zip) y mapeado (fmap) tus arrays de vértices a la perfección, es hora de crear un array de primitivas. La manera más simple de crear uno es con esta función:

toPrimitiveArray :: PrimitiveTopology p -> VertexArray () a -> PrimitiveArray p a

Siempre vas a necesitar una topología de primitivas, ademas de tu array de vértices, para crear un PrimitiveArray. La topología de primitivas denota como los vértices deben conectarse para formar primitivas, y es uno de estos constructores:

data PrimitiveTopology p where
  TriangleList :: PrimitiveTopology Triangles
  TriangleStrip :: PrimitiveTopology Triangles
  TriangleFan :: PrimitiveTopology Triangles
  LineList :: PrimitiveTopology Lines
  LineStrip :: PrimitiveTopology Lines
  LineLoop :: PrimitiveTopology Lines
  PointList :: PrimitiveTopology Points

En la mayoría de los casos vas a trabajar con triángulos. Veamos como se ven las tres topologias de triángulos:

En un TriangleStrip, cada vértice forma un triangulo con los dos vértices previos, alternando el camino de los vértices para cada triangulo. Esto significa que el primer triangulo es formado por los vértices 1-2-3 en ese orden, el siguiente por 2-4-3, luego por 3-4-5, 4-6-5, y así sucesivamente. Para TriangleFan, cada triangulo es formado por el primer vértice en el array junto con cada dos vértices consecutivos, en ese orden. Para TriangleList, cada tres vértices simplemente forman un triangulo; no se comparte ningún vértice entre los triángulos.

Los vértices siempre vienen en orden antihorario para un triangulo de cara orientada hacia el frente (lo cual significa que todos los triángulos en la imagen de arriba, excepto el de más a la derecha, están orientados con cara hacia el fondo; solo como ejemplo de cuan intuitiva puede ser la especificación de OpenGL). La orientación de la cara de un triangulo va a ser importante luego, cuando lo rastericemos, en ese momento podrás elegir solo rasterizar los triángulos de cara hacia el frente o hacia el fondo.

Los arrays de primitivas no se pueden recortar como los de vértices, pero poseen una instancia de Functor así que puedes hacer fmap sobre ellos exactamente como con los arrays de vértices. También tienen una instancia de Monoid, que permite concatenar dos PrimitiveArray juntos en uno solo usando mappend. Esto hace posible crea un PrimitiveArray conformado por varias tiras de triángulos disjuntas, pero maneras más eficientes de lograrlo serán presentadas en las siguientes dos secciones.

Arrays de indices

Es común que un vértice sea usado no solo por dos triángulos consecutivos en una tira, sino también por triángulos de otra tira. Seria un desperdicio duplicar para cada tira todos los datos de los vértices compartidos, y por esta razón puedes usar un index array como reemplazo:

toPrimitiveArrayIndexed :: PrimitiveTopology p -> IndexArray -> VertexArray () a -> PrimitiveArray p a

En vez de formas primitivas tomando vértices consecutivos en un VertexArray, esta función va a tomar los indices de un IndexArray y usarlos para referenciar vértices del VertexArray. Múltiples elementos en el IndexArray pueden referirse al mismo vértice. La topología de primitivas funciona de la misma manera para esta función, pero es aplicada al IndexArray. Por ejemplo, si TriangleStrip es usado, el primer triangulo es formado por los vértices referenciados por los primeros tres indices, el siguiente esta formado por el segundo, el cuarto y el tercer indice, y así sucesivamente.

Puedes crear un IndexArray usando

newIndexArray :: forall os f b a. (BufferFormat b, Integral a, IndexFormat b ~ a) => Buffer os b -> Maybe a -> Render os f IndexArray

Muy parecido a crear un VertexArray, pero el tipo de los elementos del Buffer a partir del cual lo creas, esta también acotado por el siguiente type family:

type family IndexFormat a where
  IndexFormat (B Word32) = Word32  
  IndexFormat (BPacked Word16) = Word16  
  IndexFormat (BPacked Word8) = Word8

Esto significa que los indices pueden ser Word32, Word16 o Word8. ¿Recuerdas que previamente mencioné que todos los tipos de los elementos del buffer necesitaban tener una alineación de 4-bytes? Los arrays de indices realmente requieren que todos los elementos estén empaquetados, pero todavía soporta indices de tipo Word16 y Word8. Esto significa que los buffers de estos dos tipos de elementos no pueden ser usados como arrays de vértices. Esto es por lo que la representación de Word16 y Word8 es BPacked Word16 y BPacked Word8. Estos funcionan exactamente como sus contrapartes B, con la excepción de que no hay instancias de VertexInput para ningun BPacked a. VertexInput es el type class usado en la creación de streams de primitivas desde arrays de primitivas, lo cual vamos a usar en la siguiente parte de este tutorial. Como puedes suponer a esta altura, el type family IndexFormat a evalúa a los mismos tipos que el tipo asociado HostFormat a.

Además de un buffer de indices, newIndexArray también toma un Maybe a como argumento. Esto denota un indice opcional llamado primitive restart, es decir un valor de indice especial, que si es encontrado en el array de indices mientras se procesan las primitivas, señala que la topología actual debe terminar y el siguiente indice es el comienzo de una nueva topología. Esto hace posible tener múltiples tiras de triángulos en un solo IndexArray con solo separarlos con un indice especial, lo cual es mucho más eficiente que concatenar múltiples PrimitiveStream usando su instancia de Monoid.

Los arrays de indices pueden ser recortados como cualquier array de vértices, pero siempre usando las funciones takeIndices y dropIndices. No poseen instancia de Functor (lo cual no tiene sentido) ni de Monoid.

Arrays de primitivas instanciados

La ultima cosa que voy a mostrarte en este episodio son los arrays de primitivas instanciados. Imagina que quieres crear una malla de triángulos de un templo, donde tienes muchos pilares idénticos ubicado en fila. En vez de duplicar los triángulos de cada pilar, o hacer un solo array de primitivas para concatenarlo consigo mismo múltiples veces, puedes crear un array de primitivas instanciado. La función de ve así:

toPrimitiveArrayInstanced :: PrimitiveTopology p -> (a -> b -> c) -> VertexArray () a -> VertexArray t b -> PrimitiveArray p c

Es muy similar a la función zipVertices en que toma dos VertexArray y una función binaria para combinar los vértices de estos arrays, pero toPrimitiveArrayInstanced no junta los dos arrays. En cambio, va a crear un array de primitivas desde el primer array de vértices para cada vértice del segundo array, y concatenar los resultados. En nuestro ejemplo de los pilares del templo, el primer array contiene entonces la tira para un solo pilar, mientras que el segundo array contiene una posición para instanciar cada pilar, resultado en un array de primitivas donde cada vértice contiene su posición individual dentro del pilar, asi como la posición de la instancia dentro del templo. Necesitarias entonces un shader que combine estas dos posiciones juntas en la posición final. Esta es la manera más eficiente de renderizar múltiples instancias de un mismo objeto.

Si quieres usar un arrays de primitivas instanciados y array de primitivas indexados al mismo tiempo, hay una función para hacer eso también:

toPrimitiveArrayIndexedInstanced :: PrimitiveTopology p -> IndexArray -> (a -> b -> c) -> VertexArray () a -> VertexArray t b -> PrimitiveArray p c

Para hacer la instanciación aun más poderosa, puedes replicar los vértices en un array un numero fijo de veces cada uno y luego comprimirlo con otro array y usar el resultado como instancias en toPrimitiveArrayInstanced. Por ejemplo, podrías tener un array de vértices con tres diferentes colores, replicar cada color 5 veces, luego comprimirlo con un array de 15 posiciones, y usar esto como instancias de nuestro templo para tener 15 pilares de colores en tres diferentes graduaciones para variar. La función que usarías para hacer esto es:

replicateEach :: Int -> VertexArray t a -> VertexArray Instances a

Esto va a replicar cada vértice en el array de argumento tantas veces como sea dictado por el primer argumento. Fijate que el tipo de Instances en el primer parámetro de tipo del resultante VertexArray. Quizás hayas notado que este parámetro había sido previamente () o solamente t. Si este parámetro de VertexArray es Instances entonces el VertexArray solo puede ser usado para instancias, es decir como ultimo argumento en una llamada a toPrimitiveArrayInstanced o toPrimitiveArrayIndexedInstanced. Si vas hacia atrás y miras los tipos de las funciones que toman o retornan VertexArray más arriba, vas a notar que:

replicateEach retorna un VertexArray que debe ser usado como instancia.
dropVertices no puede ser usado en ningún VertexArray que deba ser usado como instancia.
zipVertices retorna un VertexArray que debe ser usado como instancia si alguno de los arrays de entrada debe ser usado como instancia.

Fui un poco injusto ahora, porque esto ultimo no era algo que pudieses notar solo mirando el tipo de la la función, necesitabas esta definición también:

type family Combine t t' where
  Combine () Instances = Instances  
  Combine Instances () = Instances  
  Combine Instances Instances = Instances  
  Combine () () = ()

Cuando tienes tu PrimitiveArray, la información de tipo ya sea si fue instanciado, indexado o ambos, se ha ido. Esto significa que puedes usar mappend sobre un array de primitivas instanciado junto con uno no instanciado, y que el shader al cual envías un array de primitivas no le importa si era instanciado o indexado.

Esta vez no hay ejemplos de código, así que voy a dejar como ejercicio aplicar lo que aprendiste esta vez en el ejemplo de la parte anterior. La próxima vez finalmente vamos a abordar Shader!

Comments are not open for this post yet.

Programación de GPU en Haskell usando GPipe - Parte 1

2016-04-27T03:23:00-03:00

Posted on 2016-04-27 03:23:00 by rainbyte

Tags: gpipe gpu haskell opengl

Nota: estas leyendo la traducción al castellano de una serie de tutoriales en ingles sobre GPipe; la versión original, escrita por Tobias Bexelius (creador de GPipe), se encuentra aqui.

Bienvenidos a la primera parte de una serie de tutoriales sobre programación de GPU en Haskell! Vamos a usar GPipe 2.1, el cual fue recientemente publicado. GPipe 2 es un API funcional basada en OpenGl 3.3, pero este tutorial no requiere conocimiento previo sobre OpenGl, asi que si sabes Haskell (lo cual es un prerequisito), y alguna vez quisiste aprender programación grafica, ahora es el momento!

Hello triangle

Comencemos con un pequeño ejemplo, el programa "Hello world!":

{-# LANGUAGE ScopedTypeVariables, PackageImports, TypeFamilies #-}   
module Main where   
   
import Graphics.GPipe   
import qualified "GPipe-GLFW" Graphics.GPipe.Context.GLFW as GLFW  
import Control.Monad (unless)  
  
main =    
  runContextT GLFW.newContext (ContextFormatColor RGB8) $ do  
    vertexBuffer :: Buffer os (B4 Float, B3 Float) <- newBuffer 3  
    writeBuffer vertexBuffer 0 [ (V4 (-1) 1 0 1, V3 1 0 0)  
                               , (V4 0 (-1) 0 1, V3 0 1 0)  
                               , (V4 1 1 0 1,  V3 0 0 1)  
                               ]  
                        
    shader <- compileShader $ do  
      primitiveStream <- toPrimitiveStream id  
      fragmentStream <- rasterize (const (FrontAndBack, ViewPort (V2 0 0) (V2 500 500), DepthRange 0 1)) primitiveStream   
      drawContextColor (const (ContextColorOption NoBlending (V3 True True True))) fragmentStream  
      
    loop vertexBuffer shader   
    
loop vertexBuffer shader = do    
  render $ do   
    clearContextColor (V3 0 0 0)   
    vertexArray <- newVertexArray vertexBuffer  
    let primitiveArray = toPrimitiveArray TriangleList vertexArray  
    shader primitiveArray   
  swapContextBuffers  
    
  closeRequested <- GLFW.windowShouldClose   
  unless closeRequested $  
    loop vertexBuffer shader

Como puedes ver en la lista de import, se requiere un paquete opcional: GPipe-GLFW (version 1.1 o superior). Este paquete provee la funcionalidad necesaria para crear ventanas, en las cuales GPipe puede dibujar, asi como las funciones para obtener entrada de teclado y mouse. Esta funcionalidad solia ser parte de las versiones anteriores de GPipe pero, ya que muchos querian ser capaces de elegir libremente que gestor de ventanas usar, se movio a su propio paquete. Al momento de escribir este articulo solo existen bindings para GLFW, pero seguramente apareceran otros más.

Cuando realizas import Graphics.GPipe tambien obtienes los paquetes linear y Boolean completos, ya que son utilizados constantemente en aplicaciones GPipe.

Ahora estamos listos para compilar (usa -threaded como parametro para GHC, ya que GPipe-GLFW lo requiere) y ejecutar nuestro programa, el cual nos mostrará un triangulo bastante colorido en la esquina inferior izquierda de la ventana:

El contexto

Lo primero que hacemos en la función main es ejecutar runContextT. Un contexto posee dos cosas: una ventana, y un espacio de objetos. La ventana es donde tus graficos renderizados se mostraran en pantalla, y el espacio de objetos es lo que va a contener todos los datos para la GPU que tu programa define, muy parecido a lo que es un proceso para los datos usados por la CPU. runContextT crea un nuevo contexto para nostros. Toma tres argumentos: una fabrica, un formato, y una acción monadica.

La fabrica es lo que le damos a GPipe asi sabe que ventana usar. Para utilizar el paquete GPipe-GLFW, que importamos previamente, pasamos GLFW.newContext como fabrica.

El formato describe que clase de imagenes vamos a estar dibujando en la ventana, por ej. cuantos canales de color va a tener y cuantos bit por color. Tambien describe si vamos a tener un depth buffer o un stencil buffer asociado a la ventana (voy a discutir que son más adelante en este tutorial, cuando detalle como dibujar). Puedes incluso crear un contexto que no posee una ventana, por ej. si quieres usar la GPU para generar imagenes y guardarlas a disco, en vez de mostrarlas en la pantalla. Ahora vamos a quedarnos con un formato de color RGB de 8 bits por cada uno de sus tres canales, sin depth buffer ni stencil buffer. El valor que describe este formato es ContextFormatColor RGB8.

El ultimo parametro para runContextT es la acción monadica en la cual todo nuestro programa ocurre. Cuando esta acción retorna, la ventana es cerrada. Esta acción monadica tiene el tipo ContextT w os f m a. Esto es un monad transformer, es decir una monada que hereda las capacidades de otra monada de tipo m. Para ContextT, m es el tipo de la monada en la cual ejecutamos runContextT. En este, y muchos otros casos, es simplemente la monada IO. Dentro de un monad transformer puedes usar la función lift para ejecutar una acción en la monada heredada.

GPipe usa algunos trucos con los tipos de datos, para asegurar que las variables que retornan sus acciones dentro del contexto, no salen de el. Este es el mismo mecanismo que usa la monada ST para asegurarse que ninguna STRef es retornada ni usada en otra invocación a runST. El truco es que runContextT usa algo llamado rank-2 type:

runContextT :: (MonadIO m, MonadAsyncException m)
            => ContextFactory c ds w 
            -> ContextFormat c ds 
            -> (forall os. ContextT w os (ContextFormat c ds) m a) 
            -> m a

Fijate que hay un modificador forall para os, local al argumento de la acción monadica ContextT. Esto hace que cualquier objeto que referencie a os este limitado a esta acción monadica.

Es posible ejecutar otro runContextT dentro de una monada ContextT, el cual va a crear una segunda ventana con su propio contexto. Ya que estos contextos poseen su propio espacio de objetos, no pueden compartir entre ellos objetos que referencien al parametro de tipo os. Esto es una limitación bastante grande y, la mayor parte de la veces que trabajes con varias ventanas, vas a querer dejarlos usar el mismo espacio de objetos. Esto se logra usando runSharedContextT. Esta acción debe ser utilizada dentro de otro ContextT, y la acción monadica que se pasa a esta función va a usar el mismo espacio de objetos que el ContextT que la rodea, pero va a tener una ventana propia.

El parametro w en el tipo ContextT es algo definido por la fabrica del contexto. Cuando usamos GLFW.newContext, w va a ser GLFWWindow. Esto es un tipo opaco, asi que no puede usarlo directamente. A pesar de esto, nos permite usar windowShouldClose y otras acciones del paquete GPipe-GLFW dentro de nuestro contexto. En nuestro programa hello world, windowShouldClose es usado para salir del loop cuando el usuario cierra la ventana, al hacer click sobre la X en la esquina superior.

Renderizado - De eso se trata realmente

Ahora que tenemos nuestro contexto, hagamos algo de renderizado. Cualquier renderizado que haga en GPipe, va a seguir esta secuencia de operaciones:

Por lo pronto, todo renderizado de GPipe va a crear, a partir de un buffer de datos, un array de vertices que serán ensamblados en un array de primitivas. Hay tres clases de primitivas: puntos, lineas, y triangulos; pero vamos a trabajar casi exclusivamente con triangulos. El array de primitivas entonces se transforma en un stream de primitivas dentro de un shader, permitiendonos aplicar transformaciones a esos vertices. Las primitivas luego son rasterizadas, es decir son cortadas en fragmentos medidos en pixels, formando un stream de fragmentos. Este stream es luego dibujado en la ventana del contexto, o en una imagen fuera de pantalla.

En la monada ContextT, comenzamos creando un buffer de datos que es almacenado en la GPU. En nuestro ejemplo hello world de más arriba, nuestro buffer es llamado vertexBuffer y tiene 3 elementos, siendo cada uno una tupla (B4 Float, B3 Float). B4 y B3 son para un buffer las "representaciones" de V4 y V3, los tipos vectoriales del paquete linear. Voy a dar más detalles sobre que son estas "representaciones" en la siguiente parte de este tutorial, pero por ahora puedes pensar a B4 como otro nombre para V4 cuando lo usamos en un Buffer. Despues de crear el buffer, escribimos tres valores dentro de él, a partir de una lista comun.

Con una función llamada render ejecutamos otra monada, convenientemente llamada... Render. En esta monada usamos nuestro Buffer para crear un VertexArray con la función newVertexArray. Viniendo de nuestro vertexBuffer, vertexArray tendrá 3 vertices, cada uno de los cuales tiene una tupla (B4 Float, B3 Float). Ahora debes preguntarte cual es la diferencia entre un VertexArray y una Buffer. Una pregunta verdaderamente razonable, pero me temo que vamos a tener que esperar hasta la siguiente parte de este tutorial para responderla, lo siento.

Ahora que tenemos un VertexArray, vamos a usarlo para crear un PrimitiveArray de triangulos, usando la función toPrimitiveArray. El argumento TriangleList, que pasamos a la función, indica que queremos formar triangulos a partir de cada tres vertices consecutivos en un vertexArray. Como solo hay tres vertices, primitiveArray va a contener un solo triangulo.

Mirando el grafico de arriba, tenemos que convertir este PrimitiveArray en un PrimitiveStream (estaras pensando, ¿otro nombre más para la misma cosa?) pero, ¿porque en el código solo vemos shader primitiveArray?

Shaders - Un pequeño acercamiento

La caja gris en el grafico de arriba es llamada Shader. Supongo que será poco sorprendente a esta altura pero, ¡tambien es una monada! La diferencia con ambas monadas, ContextT y Render, es que no podemos ejecutarla directamente, tiene que ser primero compilada. Esta compilación es distinta a la que haces cuando ejecutas ghc, cabal, stack, o cualquier acceso directo que tengas en emacs. Esta compilación ocurre durante el tiempo de ejecución del programa, y usa un compilador que provee tu controlador grafico. La compilación puede tomar varios segundos, definitivamente no es algo que quieres hacer durante cada frame en por ej. un juego creado con GPipe.

Una monada Shader es compilada mediante la función compileShader, que es ejecutada en tu monada ContextT. compileShader retornará una función que luego puedes ejecutar en una monada Render. En nuestro ejemplo de arriba, compilamos el shader en una función a la que llamamos simplemente shader. Este shader es lo que vemos ejecutarse como ultima acción en la monada Render, pasandole primitiveArray como argumento.

Demos ahora una mirada al Shader en nuestro ejemplo. La primera acción que ejecutamos es toPrimitiveStream. Esto cargará un PrimitiveArray en algo llamado PrimitiveStream. El PrimitiveArray a cargar es seleccionado mediante la función pasada como argumento a toPrimitiveStream, en este caso id. Una monada Shader es casi como una monada Reader, ya que es cerrada sobre un entorno. Pero a diferencia de la monada Reader, no hay una acción ask por la cual puedes recuperar el entorno. En vez de esto, otras acciones, como toPrimitiveStream, van a tomar una función que extrae valores de este entorno. Cada valor del entorno no es definido hasta que el shader es ejecutado, es decir ni siquiera cuando es compilado. ¿Recuedas que pasamos primitiveArray como argumento a nuestra función shader compilada? Ese es el entorno que usamos en nuestro programa. Ya que la función pasada a toPrimitiveStream quiere extraer un PrimitiveArray del entorno, y nuestro entorno es un PrimitiveArray, simplemente usamos id.

Un PrimitiveStream es tambien una secuencia de primitivas, pero vive dentro del shader y por lo tanto podriamos mapear funciones sobre él, las cuales correran sobre la GPU. PrimitiveStream implementa el typeclass Functor, y fmap f primitiveStream retornará un nuevo PrimitiveStream que es resultado de aplicar la función f a cada vertice de cada primitiva en primitiveStream. Mapear funciones sobre streams con fmap en shaders es muchas veces más rapido que hacer la misma clase de operación en listas ordinarias, ya que estamos usando la GPU en vez del CPU. En nuestro ejemplo "Hello world", no estamos realmente haciendo nada con las primitivas en nuestro primitiveStream antes de pasarla a la función rasterize. Pero antes de entrar en ese tema, dejame mencionar cual es el tipo de datos inferido de primitiveStream:

primitiveStream :: PrimitiveStream Triangles (V4 VFloat, V3 VFloat)

Como puedes ver, los tipos B4 y B3 que teniamos en nuestro buffer (y nuestros vertex array y primitive array), fueron transformados nuevamente en V4 y V3, pero ¡los Float dentro de ellos fueron aparentemente transformados en VFloat! VFloat es en realidad un sinonimo para el tipo S V Float, el cual representa un Float desplazado a un stream de vertices en la GPU, es decir ya no es más un Float ordinario que puedes usar en cualquier función, solo puedes hacer con el cosas que la GPU soporta. Voy a discutir este tipo de datos con más detalle cuando revisemos los shaders con mayor profundidad en una parte posterior de este tutorial.

Rasterización

Incluso aunque nunca mapeemos ninguna función a nuestro primitiveStream para ejecutarla en la GPU, ni tampoco al fragmentShader que estamos por crear, todavia hay una operación que siempre hacemos en un shader la cual aprovecha el paralelismo masivo de la GPU: rasterización.

Rasterización es el proceso de mapear una primitiva, por ej. un triangulo, a una grilla y generar fragmentos medidos en pixels. Los vertices de las primitivas de entrada son usados de dos maneras: primero, todos deben proveer una posición del vertice, asi el rasterizador sabe cuantos fragmentos generar; y segundo, proveer valores que seran interpolados linealmente entre todos los vertices de la primitiva, para crear valores unicos en cada fragmento generado.

El primer argumento para rasterize, es una función que extrae tres parametros del entorno del shader: que lado de la primitiva rasterizar, las posición y el tamaño del view port, y el rango de profundidad (depth range) del fragmento. En nuestro ejemplo, sabemos todos los parametros de antemano y no necesitamos obtenerlos del entorno del shader, por eso es que usamos la función const. Los parametros que proveemos a rasterize le dicen que debe rasterizar ambos lados de cada triangulo, que el view port tiene (0,0) como coordenada inferior izquierda y tanto altura como ancho de 500 pixels, y finalmente que el rango de profundidad es [0,1]. Más sobre esto en un momento.

Las posiciones de los vertices son coordenadas 3D en un espacio de vista canonico (canonical view space). Durante la rasterización, estos van a ser transformados en el view port en espacio de pantalla en pixels, donde la posición (-1,-1,z) en el espacio de vista canonico va a ser mapeado a la esquina inferior izquierda del view port (en nuestro caso (0,0)), y (1,1,z) va a ser mapeado a la esquina superior derecha (en nuestro caso (500,500)). Para ser más precisos, el fragmento en la esquina inferior izquierda en nuestro caso va a tener realmente la coordenada de pixel (0.5,0.5), y el fragmento superior derecho que generaremos tendrá coordenada (499.5,499.5).

Todo fragmento tambien tiene un valor de profundidad en el rango [0,1]. En la rasterización nosotros especificamos, con el parametro DepthRange, como mapear la coordenada canonica z a este rango. Una coordenada z con valor -1 será mapeada al primer parametro de DepthRange, y una coordenada z con valor 1 será mapeada al segundo parametro de DepthRange. En nuestro ejemplo, nosotros mapeamos las coordenadas z en el espacio de vista canonico de rango [0,1] al rango de profundidad [0,1]. La convencion usada por Linear.Projection, y muchas otras librerias matemáticas para OpenGl, es que la coordenada z de 1 en el espacio de vista canonico es considerada la mas alejada y -1 la mas cercana, pero en realidad eres libre de usar cualquier combinacion que gustes. Cualquier fragmento con un valor fuera del rango de profundidad [0,1] será descartado, asi cualquier parte de las primitivas que intersectan la caja [(-1,-1,-1),(1,1,1)] en el espacio de vista canonico se convertirá en fragmentos en el view port. Esta caja es normalmente conocida como volumen de vista canonica (canonical view volume).

La posición de un vertice en el espacio de vista canonico se provee en realidad como un V4 VFloat, conocido como una coordenada 3D homogenea, donde V4 x y z w posee la posición 3D (x/w,y/w,z/w). Los tres vertices del triangulo en nuestro ejemplo usan 1 para la componente w, asi en este caso son simplemente coordenadas 3D comunes. Cuando se aplica "proyeccion perspectiva" (donde los objetos aparecen más pequeños cuanto más lejos estan, lo cual es standard en la mayoria de las aplicaciones 3D), la componente w no será 1. La razon por la cual el rasterizador quiere que w sea pasada de forma explicita en vez de hacer que dividamos los componentes por nuestra cuenta (mapeando una función de esa indole sobre el stream de primitivas), es que esta componente w es tambien usada cuando se realiza la interpolación de todos los demas valores del vertice. Voy a demostrar como funciona esta interpolación con corrección de perspectiva en una parte posterior, cuando veamos textures y samplers.

Ahora que hemos calculado que fragmentos generar para cada primitiva, y cuales posiciones de pantalla y valores de profundidad van a tener, podemos interpolar los demas valores de los vertices. El segundo argumento de la función rasterize es un stream de primitivas con tipo

FragmentInput a => PrimitiveStream p (V4 VFloat, a)

Y retorna un stream de fragmentos con tipo

FragmentInput a => FragmentStream (FragmentFormat a)

Esto significa que cada vertice tiene una posición homogenea como hemos discutido recien, pero tambien algun valor extra de tipo a que va a ser transformado en un valor de tipo FragmentFormat a en cada fragmento. Estos valores son producidos interpolando linealmente los valores de los vertices sobre toda la primitiva para cada fragmento. En nuestro ejemplo, a es V3 VFloat, representando el color de cada vertice. FragmentFormat a es un tipo asociado en la clase FragmentInput, y FragmentFormat (V3 VFloat) evalua a V3 FFloat. FFloat es como VFloat, una versión desplazada de Float, pero esta vez a un stream de fragmentos. Distinguimos los valores desplazados a un stream de vertices, de los valores desplazados a un stream de fragmentos, ya que la GPU no soporta exactamente el mismo conjunto de operaciones sobre ellos.

Dibujando e intercambiando

Lo ultimo que hacemos en nuestro shader, ahora que tenemos el fragmentStream, es dibujar los fragmentos en la ventana. drawContextColor toma como argumento a fragmentStream, pero tambien, asi como la mayoria de las demas acciones en la monada Shader, toma una función que extrae parametros del entorno del shader. En este caso el parametro extraido es un valor de tipo ContextColorOption, el cual especifica como los fragmentos deden ser combinados con los valores previos en la ventana. El valor que proveemos en nuestro ejemplo (nuevamente usando const, ya que no depende del entorno del shader), esta especificando que cada fragmento debe sobreescribir completamente el valor previo en la ventana. Voy a dedicar una parte completa de este tutorial a como dibujar, asi estos parametros seran explicados en detalle más adelante.

Ya que nuestra ventana fue creada con formato RGB8, el stream de fragmentos necesita contener valores de color de tipo V3 FFloat. Convenientemente, es el tipo exacto que tiene nuestro fragmentStream como resultado de la rasterización. Sin embargo, en la mayoria de los programas basados en GPipe vas a mapear funciones via fmap sobre el stream de fragmentos, para transformar los valores interpolados de la rasterizacion en el formato de color que es requerido por la ventana.

Dibujar es la unica acción en el shader que posee un efecto secundario: en este caso el buffer trasero de la ventana es alterado. Una ventana tiene (al menos) dos buffers, uno llamado buffer frontal que es mostrado en la pantalla, y otro que llamamos buffer trasero donde los shaders estan dibujando. Cuando la acción shader primitiveArray en la monada Render retorna, el buffer trasero sera actualizado. Para presentar en la pantalla esta nueva imagen renderizada, necesitamos llamar a swapContextBuffers dentro de nuestra monada ContextT. Esto le va a indicar al hardware grafico que intercambie los buffers frontal y trasero. No se va a realizar ninguna copia de memoria, sino solamente un intercambio de valores de punteros, asi que es bastante efectivo. Sin embargo, swapContextBuffers puede bloquearse momentaneamente si tratas de presentar imagenes mas rapido que la pantalla pueda actualizarse, pero esto es usualmente algo bueno, ya que de otra forma estarias gastando ciclos de GPU y CPU produciendo más imagenes de las que pueden presentarse.

Hay una linea en la acción Render de nuestro ejemplo, que omití antes descaradamente: clearContextColor (V3 0 0 0). Esta acción ocurre antes de ejecutar el shader, y es usada para setear cada pixel en los contenidos previos del buffer trasero a un valor constante, en este caso V3 0 0 0, es decir, color negro. Luego de un intercambio, los contenidos del buffer trasero son indefinidos, asi que es siempre una buena idea comenzar cada frame haciendo limpieza luego de swapContextBuffers. Limpiar y ejecutar shaders son dos acciones de la monada Render que tienen efectos secundarios.

Esto concluye la primer parte de este tutorial. La proxima vez voy a escribir detalladamente sobre Buffer y PrimitiveArray.

Comments are not open for this post yet.

Enviroment variables using fish shell

2016-02-07T02:46:00-03:00

Posted on 2016-02-07 02:46:00 by rainbyte

Tags: fish shell

Overview

Sometimes we need to export some value as an env var (eg. android sdk path). It is important to know how to do this well for smooth system administration.

Each shell has its own way to manage environment, I'm using fish shell.

In order to list current vars, standard env command is available.

Local env vars

We could run an app with custom enviroment vars, like this:

env LALA='foo bar' some_cmd

This does not always work, because env bypasses our shell.

In those situations, we could use set instead:

set -lx LALA='foo bar'; some_cmd

The -l switch means local scope, the variable is temporal.

Persistent env vars

When we need env vars to be persistent only across a session, we use global ones (-g switch):

set -gx LALA='foo bar'
some_cmd
other_cmd

Finally, we could use universal env vars, which are fully persistent across multiple sessions (-U switch).

For example, I used them in order to configure android sdk, like this:

set -U ANDROID_HOME /path/to/android/sdk

Universal env vars are persistent across reboots, you can inspect them using set -U cmd.

Path management

Changing the PATH env var is an special case. We cannot modify it directly, because it could be overwritten by the shell.

In order to overcome this situation, fish provides the fish_user_paths variable, which is automatically merged to PATH.

We could add some custom bin directory (e.g. node_modules bin dir), like this:

set -U fish_user_paths $fish_user_paths /path/to/node_modules/bin

In this way we preserve previously added paths, and the new dir is only appended to fish_user_paths.

The shell automatically adds the custom paths to the PATH var each time a session is started.

Comments are not open for this post yet.

How-to update a git submodule

2015-07-02T04:29:59-03:00

Posted on 2015-07-02 04:29:59 by rainbyte

Tags: workflow git

I do not use git submodules too often, so I'll write this recipe here, for future reference.

When we have a git repo with a submodule inside, some steps are needed to update both in sync.
This occurs because, the parent repo and the submodule, are actually two independent repos.

This is the workflow I use to update a submodule:

Work inside the submodule:

$ # edit <some files>

$ git add <some files>
Now we have some changes ready to commit and push them:

$ git commit -m "Edited <some files>

$ git push
Finally, we tell the parent repo that the submodule has changed:

$ cd the/parent/repo/path

$ git add the/submodule/repo/path

$ git commit -m "Updated the submodule"

$ git push

Syncing everytime a change is made to the submodule is not advisable, think carefully before doing it.
Sometimes we should NOT do it at all (e.g. there are compatibility breaking changes).

The parent repo could point to a previous (and safe) version of the submodule all the required time.
At least while is being adapted to assimilate the submodule updates.

Comments are not open for this post yet.

How-to decrease gnome title-bar height

2015-07-02T03:15:07-03:00

Posted on 2015-07-02 03:15:07 by rainbyte

Tags: gnome snippets css

I've started using Firefox again, and after some time I noticed that Gnome window title-bars were eating a lot of screen space.

To solve the issue, I've tried installing a plugin, but I was not too happy with the result (even after some custom tweaks).
Later, I gave up with the plugin, and started searching for other solution, reading various sources (like forums).

Finally, a good hint appeared inside the ArchWiki (a wonderful source of reliable information).
After tweaking the snippet a bit, I added it to ~/.config/gtk-3.0/gtk.css, like this:

.header-bar.default-decoration {
    padding-top: 1px;
    padding-bottom: 1px;
    font-size: 0.5em;
}

.header-bar.default-decoration .button.titlebutton {
    padding-top: 1px;
    padding-bottom: 1px;
    border-width: 0;
}

An that's all, no plugin needed and it is useful system wide (at least for apps which don't support client side decorations).

Comments are not open for this post yet.

Grouping by key with Python

2015-05-19T23:02:37-03:00

Posted on 2015-05-19 23:02:37 by rainbyte

Tags: python snippets batch

Today I had to process some data, which was inside an unordered list, using the Python language.

Some computations employed all the list items, others were based only on related ones.

The data was arranged in tuples, each one contained a main value among others.

That value (let's call it "key"), identified a relation with other tuples.

Simplifying it, quite a bit, was something similar to this:

items = [(1, "a"), (3, "q"), (2, "c"), (2, "x"), (1, "z")]

The problem could be solved using some nested "while" iterations.

But actually, I wanted something more brief and readable.

Then, I looked for an alternative, and found itertools.

First I've loaded the required module:

from itertools import groupby

Then, the final solution was much like this:

for key, group in groupby(sorted(items), lambda x: x[0]):
    # Do something with the key
    print(key)
    for tuple in group:
        # Process each tuple with same key
        print(tuple)
    # Other statements
    print("^^^^^^^^^")

There are some remarkable points in this code:

The list needs to be sorted previously, so keys can be matched up.
I've used a lambda in order to select which element is the key.
The key can be accessed individually.
Related tuples can accessed via the group variable.
Each item inside each group still contains the key.

This code would print something like this:

1
(1, 'a')
(1, 'z')
^^^^^^^^^
2
(2, 'c')
(2, 'x')
^^^^^^^^^
3
(3, 'q')
^^^^^^^^^

At the end, this method was cleaner than using iterations by hand.

Comments are not open for this post yet.

Initial post

2015-05-17T21:01:00-03:00

Posted on 2015-05-17 21:01:00 by rainbyte

Tags: hello

Just wanted to say hello for first time! :)

Let's try some example code with markdown and pygments:

#lang racket

(define (say-hello!)
  (printf "Hello world!\n"))

Comments are not open for this post yet.