KylerOlsen/YREA-SLS
KylerOlsen
/
YREA-SLS
1
0
Fork 0
Code Releases 3 Wiki Activity

Updated manage docs script

This commit is contained in:
Kyler Olsen 2025-11-02 01:10:26 -06:00
parent 9ac6750246
commit bbec991566
3 changed files with 187 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

109
manage_docs.py Normal file
View File

@ -0,0 +1,109 @@
import os
import re
import sys
import json
from pathlib import Path
filenames = [
"docs/changes.md",
"docs/overview.md",
"docs/lexical_structure.md",
"docs/primitive_types.md",
"docs/basic_operations.md",
"docs/functions.md",
"docs/control_flow.md",
"docs/data_structures.md",
"docs/type_system.md",
"docs/trait_system.md",
"docs/generic_programming.md",
"docs/advanced_topics.md",
"docs/standard_library.md",
"docs/complete_trait_reference.md",
"docs/complete_operator_reference.md",
"docs/grammar_summary.md",
"docs/module_system.md",
"docs/memory_management.md",
"docs/examples_and_tutorials.md",
]
def remove_front_matter(content):
"""Remove YAML front matter (--- ... ---) from markdown content."""
pattern = r'^---\n.*?\n---\n'
return re.sub(pattern, '', content, flags=re.DOTALL)
def extract_front_matter(content):
"""Extract YAML front matter from markdown content."""
match = re.match(r'^---\n(.*?)\n---\n', content, flags=re.DOTALL)
return match.group(1).strip() if match else None
def read_file_list(input_arg):
"""Return list of files either from arguments or a text file of paths."""
p = Path(input_arg)
if p.is_file() and p.suffix == '.txt':
with p.open(encoding='utf-8') as f:
return [line.strip() for line in f if line.strip()]
return [input_arg]
def combine_markdown(file_inputs, output_combined, output_meta_json):
"""Combine multiple markdown files into one, skipping front matter."""
files = []
for f in file_inputs:
files.extend(read_file_list(f))
combined = []
meta_info = {}
for file in files:
file_path = Path(file)
if not file_path.exists():
print(f"⚠️ Skipping missing file: {file}")
continue
text = file_path.read_text(encoding='utf-8')
front_matter = extract_front_matter(text)
if front_matter:
meta_info[file_path.name] = front_matter
cleaned = remove_front_matter(text).strip()
combined.append(f"<!-- START {file_path.name} -->\n{cleaned}\n\n<!-- END {file_path.name} -->\n")
# combined.append(f"{cleaned}\n")
Path(output_combined).write_text("\n".join(combined), encoding='utf-8')
Path(output_meta_json).write_text(json.dumps(meta_info, indent=2), encoding='utf-8')
print(f"✅ Combined file saved as: {output_combined}")
print(f"✅ Metadata JSON saved as: {output_meta_json}")
def split_by_h2(input_combined, output_dir):
"""Split a combined markdown file by H2 sections (## Heading)."""
content = Path(input_combined).read_text(encoding='utf-8')
sections = re.split(r'(?=^## )', content, flags=re.MULTILINE)
os.makedirs(output_dir, exist_ok=True)
for i, section in enumerate(sections):
if not section.strip():
continue
title_match = re.match(r'##\s*(.+)', section)
if title_match:
filename = re.sub(r'[^\w\-]+', '_', title_match.group(1)).strip('_') + ".md"
else:
filename = f"part_{i+1}.md"
Path(output_dir, filename).write_text(section.strip() + "\n", encoding='utf-8')
print(f"Created: {filename}")
if __name__ == "__main__":
if len(sys.argv) < 2:
print("Usage:")
print(" Combine files: python manage_docs.py combine")
print(" Split by H2: python manage_docs.py split")
command = sys.argv[1].lower()
if command == "combine":
combine_markdown(filenames, "stack_lang_spec.md", "metadata.json")
elif command == "split":
split_by_h2("stack_lang_spec.md", "docs")
else:
print("Unknown command. Use 'combine' or 'split'.")

21
metadata.json Normal file
View File

@ -0,0 +1,21 @@
{
"changes.md": "Title: Stack Language Specification\nPrev:\nNext:",
"overview.md": "Title: 1 Overview\nPrev: Index\nNext: Lexical Structure",
"lexical_structure.md": "Title: 2 Lexical Structure\nPrev: Overview\nNext: Primitive Types",
"primitive_types.md": "Title: 3 Primitive Types\nPrev: Lexical Structure\nNext: Basic Operations",
"basic_operations.md": "Title: 4 Basic Operations\nPrev: Primitive Types\nNext: Functions",
"functions.md": "Title: 5 Functions\nPrev: Basic Operations\nNext: Control Flow",
"control_flow.md": "Title: 6 Control Flow\nPrev: Functions\nNext: Data Structures",
"data_structures.md": "Title: 7 Data Structures\nPrev: Control Flow\nNext: Type System",
"type_system.md": "Title: 8 Type System\nPrev: Data Structures\nNext: Trait System",
"trait_system.md": "Title: 9 Trait System\nPrev: Type System\nNext: Generic Programming",
"generic_programming.md": "Title: 10 Generic Programming\nPrev: Trait System\nNext: Advanced Topics",
"advanced_topics.md": "Title: 11 Advanced Topics\nPrev: Generic Programming\nNext: Standard Library",
"standard_library.md": "Title: A Standard Library\nPrev: Advanced Topics\nNext: Complete Trait Reference",
"complete_trait_reference.md": "Title: B Complete Trait Reference\nPrev: Standard Library\nNext: Complete Operator Reference",
"complete_operator_reference.md": "Title: C Complete Operator Reference\nPrev: Complete Trait Reference\nNext: Grammar Summary",
"grammar_summary.md": "Title: D Grammar Summary\nPrev: Complete Operator Reference\nNext: Module System",
"module_system.md": "Title: E Module System\nPrev: Grammar Summary\nNext: Memory Management",
"memory_management.md": "Title: F Memory Management\nPrev: Module System\nNext: Examples and Tutorials",
"examples_and_tutorials.md": "Title: G Examples & Tutorials\nPrev: Memory Management\nNext:"
}

57
stack_lang_spec.md
View File

@ -1,3 +1,4 @@
<!-- START changes.md -->
# Stack Language Specification # Stack Language Specification
**Version**: 0.8 **Version**: 0.8
@ -72,6 +73,9 @@
--- ---
<!-- END changes.md -->
<!-- START overview.md -->
## 1. Overview ## 1. Overview
A statically-typed, stack-based language with pure postfix notation combining the execution model of HP's RPL, the type system of C and Rust, and modern array operations from Uiua. A statically-typed, stack-based language with pure postfix notation combining the execution model of HP's RPL, the type system of C and Rust, and modern array operations from Uiua.
@ -144,6 +148,9 @@ This specification is organized to support both learning and reference:
--- ---
<!-- END overview.md -->
<!-- START lexical_structure.md -->
## 2. Lexical Structure ## 2. Lexical Structure
### 2.1 Comments ### 2.1 Comments
@ -216,6 +223,9 @@ false
--- ---
<!-- END lexical_structure.md -->
<!-- START primitive_types.md -->
## 3. Primitive Types ## 3. Primitive Types
The language provides several built-in primitive types for common values: The language provides several built-in primitive types for common values:
@ -250,6 +260,9 @@ Raw pointers (`ptr`) are a future feature. See [Appendix F](./memory_management.
--- ---
<!-- END primitive_types.md -->
<!-- START basic_operations.md -->
## 4. Basic Operations ## 4. Basic Operations
### 4.1 Stack Operations ### 4.1 Stack Operations
@ -378,6 +391,9 @@ Bitwise operations work on integer types:
--- ---
<!-- END basic_operations.md -->
<!-- START functions.md -->
## 5. Functions ## 5. Functions
Functions are user-defined procedures that encapsulate reusable code. They are the primary abstraction mechanism in the language. Functions are user-defined procedures that encapsulate reusable code. They are the primary abstraction mechanism in the language.
@ -511,6 +527,9 @@ The `lambda` operator converts a TokenString into a callable code block that can
--- ---
<!-- END functions.md -->
<!-- START control_flow.md -->
## 6. Control Flow ## 6. Control Flow
### 6.1 Conditionals ### 6.1 Conditionals
@ -664,6 +683,9 @@ result {
--- ---
<!-- END control_flow.md -->
<!-- START data_structures.md -->
## 7. Data Structures ## 7. Data Structures
### 7.1 Structs ### 7.1 Structs
@ -815,6 +837,9 @@ These operations take TokenString arguments containing function bodies:
--- ---
<!-- END data_structures.md -->
<!-- START type_system.md -->
## 8. Type System ## 8. Type System
### 8.1 Types vs Traits ### 8.1 Types vs Traits
@ -967,6 +992,9 @@ Option<Point<f64>> // Option containing a Point of f64s
--- ---
<!-- END type_system.md -->
<!-- START trait_system.md -->
## 9. Trait System ## 9. Trait System
### 9.1 What are Traits ### 9.1 What are Traits
@ -1180,6 +1208,9 @@ This section provides a brief overview of all standard traits. For complete defi
--- ---
<!-- END trait_system.md -->
<!-- START generic_programming.md -->
## 10. Generic Programming ## 10. Generic Programming
### 10.1 Type Parameters ### 10.1 Type Parameters
@ -1353,6 +1384,9 @@ When inheriting from generic traits, you must either:
--- ---
<!-- END generic_programming.md -->
<!-- START advanced_topics.md -->
## 11. Advanced Topics ## 11. Advanced Topics
### 11.1 Dynamic Code Evaluation ### 11.1 Dynamic Code Evaluation
@ -1460,6 +1494,9 @@ The standard library provides I/O, string operations, type conversions, and util
--- ---
<!-- END advanced_topics.md -->
<!-- START standard_library.md -->
## Appendix A: Standard Library ## Appendix A: Standard Library
This appendix provides a complete alphabetical reference of all standard library functions and operations. This appendix provides a complete alphabetical reference of all standard library functions and operations.
@ -1802,6 +1839,9 @@ This appendix provides a complete alphabetical reference of all standard library
--- ---
<!-- END standard_library.md -->
<!-- START complete_trait_reference.md -->
## Appendix B: Complete Trait Reference ## Appendix B: Complete Trait Reference
This appendix contains all built-in trait definitions with complete documentation, organized alphabetically. This appendix contains all built-in trait definitions with complete documentation, organized alphabetically.
@ -2571,6 +2611,9 @@ This appendix contains all built-in trait definitions with complete documentatio
--- ---
<!-- END complete_trait_reference.md -->
<!-- START complete_operator_reference.md -->
## Appendix C: Complete Operator Reference ## Appendix C: Complete Operator Reference
This appendix provides a complete alphabetical reference of all operators in the language. This appendix provides a complete alphabetical reference of all operators in the language.
@ -3117,6 +3160,9 @@ This appendix provides a complete alphabetical reference of all operators in the
--- ---
<!-- END complete_operator_reference.md -->
<!-- START grammar_summary.md -->
## Appendix D: Grammar Summary ## Appendix D: Grammar Summary
This appendix provides a concise grammar reference. For complete specifications of language constructs (fn, struct, trait, impl, etc.), see the `::Implementable` trait in Appendix B. This appendix provides a concise grammar reference. For complete specifications of language constructs (fn, struct, trait, impl, etc.), see the `::Implementable` trait in Appendix B.
@ -3222,6 +3268,9 @@ Language constructs (fn, struct, trait, impl, enum, union, inher) are defined by
--- ---
<!-- END grammar_summary.md -->
<!-- START module_system.md -->
## Appendix E: Module System (Future) ## Appendix E: Module System (Future)
**Current State**: All standard library functions and traits are automatically in scope. **Current State**: All standard library functions and traits are automatically in scope.
@ -3268,6 +3317,9 @@ Language constructs (fn, struct, trait, impl, enum, union, inher) are defined by
--- ---
<!-- END module_system.md -->
<!-- START memory_management.md -->
## Appendix F: Memory Management (Future) ## Appendix F: Memory Management (Future)
The language specification currently does not include heap memory management. This appendix documents potential future approaches. The language specification currently does not include heap memory management. This appendix documents potential future approaches.
@ -3355,6 +3407,9 @@ This would provide stronger type safety but add complexity to the type checker.
--- ---
<!-- END memory_management.md -->
<!-- START examples_and_tutorials.md -->
## Appendix G: Examples & Tutorials ## Appendix G: Examples & Tutorials
### G.1 Tutorial: First Steps ### G.1 Tutorial: First Steps
@ -3781,3 +3836,5 @@ dup ::x get print // Prints: 3.0
``` ```
--- ---
<!-- END examples_and_tutorials.md -->