BembaJS Core

BembaJS Core - The compiler and runtime engine for Bemba language 🇿🇲

📦 Installation

npm install bembajs-core

🚀 Quick Start

const { compile, parse, transform, generate } = require('bembajs-core');

// Compile Bemba code to HTML/JavaScript
const result = compile(`
  pangaIpepa('Home', {
    umutwe: 'Mwaiseni ku BembaJS!',
    ilyashi: 'Welcome to BembaJS framework'
  });
`);

console.log(result);

🔧 API Reference

compile(code, options)

Compiles Bemba code to HTML/JavaScript.

Parameters:

• code (string) - Bemba source code
• options (object) - Compilation options

Returns: Compiled HTML string

Example:

const html = compile(`
  pangaWebusaiti("My App", {
    ifiputulwa: [{
      umutwe: "Welcome",
      ilyashi: "Hello from BembaJS!",
      amabatani: [{
        ilembo: "Click Me",
        pakuKlikisha: "londolola('Hello!')"
      }]
    }]
  });
`);

parse(code)

Parses Bemba code into an Abstract Syntax Tree (AST).

Parameters:

• code (string) - Bemba source code

Returns: AST object

Example:

const ast = parse(`
  fyambaIcipanda('Button', {
    ilembo: 'Click Me',
    pakuKlikisha: 'handleClick()'
  });
`);

transform(ast)

Transforms Bemba AST to React-compatible AST.

Parameters:

• ast (object) - Bemba AST

Returns: React-compatible AST

generate(ast)

Generates JavaScript code from AST.

Parameters:

• ast (object) - React-compatible AST

Returns: Generated JavaScript string

🏗️ Architecture

BembaJS Core consists of four main components:

1. Lexer (BembaLexer)

Tokenizes Bemba source code into tokens.

const { BembaLexer } = require('bembajs-core');
const lexer = new BembaLexer();
const tokens = lexer.tokenize(code);

2. Parser (BembaParser)

Parses tokens into an Abstract Syntax Tree.

const { BembaParser } = require('bembajs-core');
const parser = new BembaParser();
const ast = parser.parse(tokens);

3. Transformer (BembaTransformer)

Transforms Bemba AST to React-compatible AST.

const { BembaTransformer } = require('bembajs-core');
const transformer = new BembaTransformer();
const reactAST = transformer.transform(bembaAST);

4. Generator (BembaGenerator)

Generates JavaScript/React code from AST.

const { BembaGenerator } = require('bembajs-core');
const generator = new BembaGenerator();
const jsCode = generator.generate(reactAST);

🎯 Bemba Language Features

Components

fyambaIcipanda('MyComponent', {
  umutwe: 'Component Title',
  ilyashi: 'Component content',
  amabatani: [{
    ilembo: 'Button Text',
    pakuKlikisha: 'handleClick()'
  }]
});

Pages

pangaIpepa('Home', {
  umutwe: 'Welcome to BembaJS',
  ilyashi: 'Build amazing web applications'
});

API Routes

pangaMaapi('/api/hello', {
  method: 'GET',
  response: 'Hello from BembaJS!'
});

Hooks

// State management
const [count, setCount] = useUmubili(0);

// Effects
useMulemba(() => {
  console.log('Component mounted');
}, []);

// Context
const theme = useMukulu('theme');

🔧 Constants

Bemba Keywords

const { BEMBA_KEYWORDS } = require('bembajs-core');
console.log(BEMBA_KEYWORDS);
// Output: ['fyambaIcipanda', 'pangaIpepa', 'pangaMaapi', ...]

Bemba Folders

const { BEMBA_FOLDERS } = require('bembajs-core');
console.log(BEMBA_FOLDERS);
// Output: { pages: 'amapeji', components: 'ifikopo', api: 'maapi', ... }

🧪 Testing

npm test

📖 Examples

Basic Component

const { compile } = require('bembajs-core');

const code = `
  fyambaIcipanda('Welcome', {
    umutwe: 'Mwaiseni ku BembaJS!',
    ilyashi: 'This is a Bemba component',
    amabatani: [{
      ilembo: 'Get Started',
      pakuKlikisha: 'startApp()'
    }]
  });
`;

const result = compile(code);

Form Component

const code = `
  fyambaIcipanda('ContactForm', {
    umutwe: 'Contact Us',
    ilyashi: 'Send us a message',
    amabatani: [{
      ilembo: 'Submit',
      pakuKlikisha: 'submitForm()'
    }]
  });
`;

🔗 Related Packages

• bembajs - Main CLI and SDK
• create-bembajs - Project scaffolding

📄 License

MIT License - see LICENSE file for details.

🤝 Contributing

We welcome contributions! Please see our Contributing Guide.

Made with ❤️ in Zambia 🇿🇲