Binary Logic Playground

This project removes abstraction.

You will stop thinking in:

• Decimal numbers
• Boolean keywords
• High-level arithmetic

And start thinking in:

• Bits
• Masks
• Shifts
• Two’s complement
• Binary truth tables

If you truly understand this project, you understand how computers compute.

Project Objective

Build an interactive CLI tool that allows you to:

• Convert decimal to binary (fixed width)
• Convert binary to decimal
• Apply bitwise operations visually
• Perform left and right shifts
• Explore two’s complement for negative numbers
• Apply custom bit masks
• Generate truth tables
• Change binary width dynamically

This is not just about Python syntax.

It is about computational thinking at the bit level.

System Architecture

Your CLI must follow this structure:

1. CLI Loop
2. Command Parsing
3. Input Validation
4. Binary Formatter
5. Operation Engine
6. Output Renderer
7. Error Handling

Keep parsing and execution separate.

Step 1 - Binary Formatting Engine

We need controlled-width formatting.

def to_binary(n, width=8):
    mask = (1 << width) - 1
    return format(n & mask, f"0{width}b")

def to_decimal(binary_str):
    return int(binary_str, 2)

Test:

print(to_binary(5))        # 00000101
print(to_decimal("1010"))  # 10

Reflection:

• Why do we mask with (1 << width) - 1?
• What happens if width is too small?

Step 2 - CLI Command Format

Example commands:

bin 10
dec 1010
and 5 3
or 5 3
xor 5 3
not 5
shiftl 5 2
shiftr 5 1
mask 5 0b0010
truth and
width 16
exit

Parsing:

tokens = raw.split()
command = tokens[0].lower()
args = tokens[1:]

Strict validation is required.

Step 3 - Bitwise Operations (Visual Mode)

When user types:

and 5 3

Output should show:

A    = 00000101
B    = 00000011
AND  = 00000001
DEC  = 1

Implementation:

def display_binary_op(a, b, op, result, width):
    print("A   =", to_binary(a, width))
    print("B   =", to_binary(b, width))
    print(op.upper(), "=", to_binary(result, width))
    print("DEC =", result)

Core operators:

a & b
a | b
a ^ b
~a
a << n
a >> n

Step 4 - Two’s Complement

Example:

print(to_binary(-5, 8))

Expected output:

11111011

Two’s complement steps:

1. Convert 5 → 00000101
2. Invert bits → 11111010
3. Add 1 → 11111011

Reflection:

• Why does ~5 equal -6?
• Why does Python not overflow integers?

Step 5 - Bit Mask Playground

Example:

mask 5 0b0010

Implementation:

result = 5 & 0b0010

Real-world uses:

• Permission systems
• Feature flags
• Network protocol headers
• Embedded hardware registers

Challenge:

read  = 0b001
write = 0b010
exec  = 0b100

Combine flags and test them.

Step 6 - Shifting Logic

Test:

shiftl 5 2

Binary transformation:

00000101 << 2 → 00010100

Which equals 20.

Reflection:

• Why does left shift multiply by powers of two?
• Why does right shift behave like floor division?

Step 7 - Truth Table Generator

Command:

truth and

Output:

A B | R
0 0 | 0
0 1 | 0
1 0 | 0
1 1 | 1

Implementation:

def truth_table(op):
    for a in (0, 1):
        for b in (0, 1):
            if op == "and":
                r = a & b
            elif op == "or":
                r = a | b
            elif op == "xor":
                r = a ^ b
            print(a, b, "|", r)

This connects boolean algebra with bitwise logic.

Error Handling Requirements

You must handle:

• Invalid binary strings
• Negative shift values
• Missing arguments
• Unknown commands
• Non-integer values

Pattern:

try:
    ...
except ValueError:
    print("Invalid input.")
except Exception as e:
    print("Error:", e)

Never allow the program to crash.

Advanced Extensions

• Binary addition with carry visualization
• Binary subtraction visualizer
• Hexadecimal mode
• Random binary quiz mode
• Bit toggling interface
• Display sign bit explicitly

Engineering Reflection

After completing this project, you should be able to answer:

1. Why does Python not overflow integers?
2. Why is masking required to simulate fixed-width systems?
3. Why does ~n equal -(n + 1)?
4. Why are flags stored as bits instead of booleans?
5. How would you design a role-based permission system using masks?

If you cannot explain these clearly, revisit the project.

Final Insight

Computers do not understand:

• Decimal
• Keywords
• Human language

They understand:

• Voltage
• Bits
• Logical gates

This playground connects abstraction to reality.

If you understand this deeply, you understand how machines compute.