selfies-js 0.3.3 → 0.3.5

package/README.md

@@ -112,6 +112,11 @@ selfies list molecules.selfies
 # Reference other fragments
 [ethanol] = [ethyl][hydroxyl]
 
+# Use repeat() macro for patterns
+[benzene] = repeat([C][=C], 3)[Ring1][=Branch1]
+[carbon_chain] = repeat([C], 10)
+[polymer] = repeat([monomer], 5)
+
 # Import from other files
 import "./other-file.selfies"                    # import all
 import [methyl, ethyl] from "./fragments.selfies" # import specific
@@ -156,6 +161,33 @@ await initRDKit()
 const svg = await renderSelfies('[C][C][O]', { width: 300, height: 300 })
 ```
 
+## Repeat Macro
+
+The `repeat()` macro allows you to repeat molecular patterns, perfect for polymers and long chains:
+
+```selfies
+# Benzene ring
+[benzene] = repeat([C][=C], 3)[Ring1][=Branch1]
+
+# Carbon chains
+[decane] = repeat([C], 10)
+[pentadecane] = repeat([C], 15)
+
+# Polymer repeat units
+[PE_unit] = [C][C]
+[polyethylene_trimer] = repeat([PE_unit], 3)
+
+# References work too
+[monomer] = [C][Branch1][C][Cl][C]
+[pvc_hexamer] = repeat([monomer], 6)
+```
+
+The pattern can be:
+- **Primitive tokens**: `repeat([C], 10)` for a 10-carbon chain
+- **Complex patterns**: `repeat([C][=C], 3)` for alternating double bonds
+- **Named references**: `repeat([unit], 5)` to repeat a defined fragment
+- **Combined**: `[molecule] = [N]repeat([C], 3)[O]` with tokens before/after
+
 ## VS Code Extension
 
 Get live visualization as you author `.selfies` files. See the molecular structure update line-by-line as you navigate your code.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "selfies-js",
-  "version": "0.3.3",
+  "version": "0.3.5",
   "description": "Pure JavaScript SELFIES encoder/decoder with DSL for molecular composition",
   "type": "module",
   "main": "src/index.js",

package/src/decoder.js

@@ -415,10 +415,81 @@ export function deriveBranch(tokens, startIndex, maxDerive, initState, rootAtom,
     const token = tokens[startIndex + consumed]
     const content = token.slice(1, -1)
 
-    // Skip structural tokens in branch
-    if (content.includes('Branch') || content.includes('Ring') ||
-        content.includes('ch') || content.includes('ng')) {
+    // Handle Ring tokens inside branch
+    if (content.includes('Ring') || content.includes('ng')) {
+      const ringInfo = processRingSymbol(token)
+      if (!ringInfo) {
+        throw new Error(`Invalid ring token in branch: ${token}`)
+      }
+      if (state === 0) {
+        throw new Error(`Ring ${token} at invalid state 0 inside branch`)
+      }
+
+      const { order: requestedOrder, L } = ringInfo
+      const [bondOrder, nextState] = nextRingState(requestedOrder, state)
+
+      consumed++
+      derived++ // Ring counts toward derive limit
+
+      if (consumed >= tokens.length - startIndex) {
+        state = nextState
+        break
+      }
+
+      const Q = readIndexFromTokens(tokens, startIndex + consumed, L)
+      consumed += Q.consumed
+      derived += Q.consumed // Q index tokens also count
+
+      const targetIndex = Math.max(0, prevAtomIndex - (Q.value + 1))
+      if (targetIndex !== prevAtomIndex) {
+        handleRingClosure(targetIndex, prevAtomIndex, bondOrder, bonds, rings)
+      }
+
+      state = nextState
+      continue
+    }
+
+    // Handle nested Branch tokens - recursively process them
+    if (content.includes('Branch') || content.includes('ch')) {
+      const branchInfo = processBranchSymbol(token)
+      if (!branchInfo) {
+        throw new Error(`Invalid branch token in branch: ${token}`)
+      }
+      if (state <= 1) {
+        throw new Error(`Branch ${token} at invalid state ${state} inside branch`)
+      }
+
+      const { order: branchOrder, L } = branchInfo
+      const [branchInitState, nextState] = nextBranchState(branchOrder, state)
+
       consumed++
+      derived++ // Branch counts toward derive limit
+
+      if (consumed >= tokens.length - startIndex) {
+        state = nextState
+        break
+      }
+
+      // Read Q index
+      const Q = readIndexFromTokens(tokens, startIndex + consumed, L)
+      consumed += Q.consumed
+      derived += Q.consumed // Q index tokens count
+
+      // Recursively derive nested branch
+      const nestedResult = deriveBranch(
+        tokens,
+        startIndex + consumed,
+        Q.value + 1,
+        branchInitState,
+        prevAtomIndex,
+        atoms,
+        bonds,
+        rings
+      )
+      consumed += nestedResult.consumed
+      derived += nestedResult.derived
+
+      state = nextState
       continue
     }
 

package/src/dsl/analyzer.js

@@ -25,10 +25,23 @@ export function getDependencies(program, name) {
 
   const dependencies = []
   for (const token of definition.tokens) {
-    const tokenName = token.slice(1, -1) // Remove brackets
-    if (program.definitions.has(tokenName)) {
-      if (!dependencies.includes(tokenName)) {
-        dependencies.push(tokenName)
+    if (typeof token === 'object' && token.type === 'REPEAT_CALL') {
+      // Extract dependencies from repeat pattern
+      const patternTokens = tokenizePattern(token.pattern)
+      for (const patternToken of patternTokens) {
+        const tokenName = patternToken.slice(1, -1) // Remove brackets
+        if (program.definitions.has(tokenName)) {
+          if (!dependencies.includes(tokenName)) {
+            dependencies.push(tokenName)
+          }
+        }
+      }
+    } else if (typeof token === 'string') {
+      const tokenName = token.slice(1, -1) // Remove brackets
+      if (program.definitions.has(tokenName)) {
+        if (!dependencies.includes(tokenName)) {
+          dependencies.push(tokenName)
+        }
       }
     }
   }
@@ -36,6 +49,36 @@ export function getDependencies(program, name) {
   return dependencies
 }
 
+/**
+ * Tokenizes a pattern string into SELFIES tokens
+ * @param {string} pattern - Pattern string like '[C][=C]'
+ * @returns {string[]} Array of tokens
+ */
+function tokenizePattern(pattern) {
+  const tokens = []
+  let i = 0
+
+  while (i < pattern.length) {
+    if (pattern[i] === '[') {
+      // Find the closing bracket
+      let j = i + 1
+      while (j < pattern.length && pattern[j] !== ']') {
+        j++
+      }
+      if (j < pattern.length) {
+        tokens.push(pattern.slice(i, j + 1))
+        i = j + 1
+      } else {
+        i++
+      }
+    } else {
+      i++
+    }
+  }
+
+  return tokens
+}
+
 /**
  * Gets the names that depend on a definition
  * @param {Object} program - Program object

package/src/dsl/parser.js

@@ -222,18 +222,37 @@ function parseRepeatCall(tokens, startIndex) {
   }
   i++
 
-  // Expect STRING (pattern)
-  if (i >= tokens.length || tokens[i].type !== TokenType.STRING) {
-    // Skip to closing paren or end of line on error
+  // Collect SELFIES_TOKENs as pattern until we hit COMMA
+  const patternTokens = []
+  const patternStart = i
+
+  while (i < tokens.length &&
+         tokens[i].type !== TokenType.COMMA &&
+         tokens[i].type !== TokenType.RPAREN &&
+         tokens[i].type !== TokenType.NEWLINE &&
+         tokens[i].type !== TokenType.EOF) {
+    if (tokens[i].type === TokenType.SELFIES_TOKEN) {
+      patternTokens.push(tokens[i].value)
+      i++
+    } else {
+      const skipToEnd = skipToRParenOrEOL(tokens, i)
+      return {
+        error: createDiagnostic('Expected SELFIES tokens or name references in pattern', 'error', tokens[i]),
+        nextIndex: skipToEnd
+      }
+    }
+  }
+
+  if (patternTokens.length === 0) {
     const skipToEnd = skipToRParenOrEOL(tokens, i)
     return {
-      error: createDiagnostic('Expected string pattern as first argument', 'error', tokens[i] || repeatToken),
+      error: createDiagnostic('Pattern cannot be empty', 'error', tokens[patternStart] || repeatToken),
       nextIndex: skipToEnd
     }
   }
-  const patternToken = tokens[i]
-  const pattern = patternToken.value.slice(1, -1) // Remove quotes
-  i++
+
+  // Join pattern tokens into a single string
+  const pattern = patternTokens.join('')
 
   // Expect COMMA
   if (i >= tokens.length || tokens[i].type !== TokenType.COMMA) {

package/src/dsl/resolver.test.js

@@ -100,81 +100,82 @@ describe('resolveAll', () => {
 
 describe('repeat macro', () => {
   test('repeats a simple token sequence', () => {
-    const program = parse('[triple_carbon] = repeat(\'[C]\', 3)')
+    const program = parse('[triple_carbon] = repeat([C], 3)')
     expect(resolve(program, 'triple_carbon')).toBe('[C][C][C]')
   })
 
   test('repeats a complex token sequence', () => {
-    const program = parse('[benzene] = repeat(\'[C][=C]\', 3)[Ring1][=Branch1]')
+    const program = parse('[benzene] = repeat([C][=C], 3)[Ring1][=Branch1]')
     expect(resolve(program, 'benzene')).toBe('[C][=C][C][=C][C][=C][Ring1][=Branch1]')
   })
 
   test('repeats with count of 1', () => {
-    const program = parse('[single] = repeat(\'[C][O]\', 1)')
+    const program = parse('[single] = repeat([C][O], 1)')
     expect(resolve(program, 'single')).toBe('[C][O]')
   })
 
   test('repeats with count of 0 produces empty sequence', () => {
-    const program = parse('[empty] = [C]repeat(\'[O]\', 0)[C]')
+    const program = parse('[empty] = [C]repeat([O], 0)[C]')
     expect(resolve(program, 'empty')).toBe('[C][C]')
   })
 
   test('repeat with reference to other definition', () => {
-    const source = '[unit] = [C][=C]\n[triple] = repeat(\'[unit]\', 3)'
+    const source = '[unit] = [C][=C]\n[triple] = repeat([unit], 3)'
     const program = parse(source)
     expect(resolve(program, 'triple')).toBe('[C][=C][C][=C][C][=C]')
   })
 
   test('multiple repeat calls in one definition', () => {
-    const program = parse('[chain] = repeat(\'[C]\', 2)repeat(\'[O]\', 2)')
+    const program = parse('[chain] = repeat([C], 2)repeat([O], 2)')
     expect(resolve(program, 'chain')).toBe('[C][C][O][O]')
   })
 
   test('repeat combined with regular tokens', () => {
-    const program = parse('[molecule] = [N]repeat(\'[C]\', 3)[O]')
+    const program = parse('[molecule] = [N]repeat([C], 3)[O]')
     expect(resolve(program, 'molecule')).toBe('[N][C][C][C][O]')
   })
 
   test('repeat with nested brackets in pattern', () => {
-    const program = parse('[branched] = repeat(\'[C][Branch1][C][O]\', 2)')
+    const program = parse('[branched] = repeat([C][Branch1][C][O], 2)')
     expect(resolve(program, 'branched')).toBe('[C][Branch1][C][O][C][Branch1][C][O]')
   })
 
   test('throws error on invalid repeat count', () => {
-    const program = parse('[bad] = repeat(\'[C]\', -1)')
+    const program = parse('[bad] = repeat([C], -1)')
     expect(() => resolve(program, 'bad')).toThrow(/count must be/)
   })
 
   test('throws error on non-numeric count', () => {
-    const program = parse('[bad] = repeat(\'[C]\', abc)')
+    const program = parse('[bad] = repeat([C], abc)')
     expect(() => resolve(program, 'bad')).toThrow()
   })
 
   test('throws error on missing arguments', () => {
-    const program = parse('[bad] = repeat(\'[C]\')')
+    const program = parse('[bad] = repeat([C])')
     expect(() => resolve(program, 'bad')).toThrow()
   })
 
-  test('throws error on malformed repeat syntax', () => {
-    const program = parse('[bad] = repeat([C], 3)')
-    expect(() => resolve(program, 'bad')).toThrow()
+  test('throws error on empty pattern', () => {
+    const program = parse('[bad] = repeat(, 3)')
+    // Parse error results in empty definition
+    expect(() => resolve(program, 'bad')).toThrow(/no tokens/)
   })
 
   test('simple polymer-like chain', () => {
-    const source = '[ch2] = [C]\n[polymer_chain] = repeat(\'[ch2]\', 5)'
+    const source = '[ch2] = [C]\n[polymer_chain] = repeat([ch2], 5)'
     const program = parse(source)
     expect(resolve(program, 'polymer_chain')).toBe('[C][C][C][C][C]')
   })
 
   test('polymer chain with decode', () => {
-    const source = '[ch2] = [C]\n[polymer_chain] = repeat(\'[ch2]\', 5)'
+    const source = '[ch2] = [C]\n[polymer_chain] = repeat([ch2], 5)'
     const program = parse(source)
     expect(resolve(program, 'polymer_chain', { decode: true })).toBe('CCCCC')
   })
 
   test('vinyl chloride monomer units', () => {
     // Each monomer as a branch structure for proper chemistry
-    const source = '[monomer] = [C][Branch1][C][Cl][C]\n[polymer] = repeat(\'[monomer]\', 3)'
+    const source = '[monomer] = [C][Branch1][C][Cl][C]\n[polymer] = repeat([monomer], 3)'
     const program = parse(source)
     // This creates a branched structure: C(Cl)CC(Cl)CC(Cl)C
     expect(resolve(program, 'polymer')).toBe('[C][Branch1][C][Cl][C][C][Branch1][C][Cl][C][C][Branch1][C][Cl][C]')

package/src/dsl/valenceValidator.js

@@ -25,26 +25,10 @@ export function validateValence(selfies, defName) {
   const errors = []
 
   try {
-    // Try to decode to SMILES - this will catch many structural issues
+    // Try to decode to SMILES - this validates the structure
+    // The decoder's state machine properly enforces valence rules
     const smiles = decode(selfies)
-
-    // Parse the SELFIES to extract atoms and bonds
-    const tokens = tokenizeSelfies(selfies)
-    const atomBonds = calculateBonds(tokens)
-
-    // Check each atom's valence
-    for (const [atom, bondCount] of Object.entries(atomBonds)) {
-      const { element, charge } = parseAtom(atom)
-      const maxBonds = getBondingCapacity(element, charge)
-
-      if (bondCount > maxBonds) {
-        errors.push({
-          message: `Valence error in '${defName}': ${element} has ${bondCount} bonds but max is ${maxBonds}`,
-          severity: 'error',
-          definitionName: defName
-        })
-      }
-    }
+    // If decoding succeeds, the SELFIES is valid
   } catch (error) {
     // If decoding fails, it's a structural error
     errors.push({