Package: braq
Braq document with 3 sections of which the last is executableBraqThe most obvious way to section a documentThis project is part of thePyrustic Open Ecosystem.Table of contentsOverviewParse a documentParse a document iterativelyRead a fileRead a file iterativelyRender a documentWrite to fileThe Section classThe Parser classMisc functionsMiscellaneousTesting and contributingInstallationOverviewBraq(pronounced/ˈbɹæk/) is a human-readable data format whose reference parser is an eponymous lightweightPythonlibrary available onPyPI.Along withParadict, Braq is a spin-off ofJesth.A Braq document is made up ofsections, each defined by aheadersurrounded by square brackets (hence the name Braq) and abodywhich is just lines of text.Instead of interpreting the lines that make sections, the Braq parser lays low and lets the programmer decide what to do with them.Because of this parsing policy, a single Braq document can contain aneclectic set of sectionssuch as notes, JSON string, help text, server configs,promptsfor a chatbot,directed graph,ascii artwork, and more.The doc generator used forPyrusticprojects consumes docstrings written in Braq.Back to topParse a documentThe library exposes theparsefunction which takes as input the text stream to be parsed, then returns adictionarywhose keys and values are strings representing headers and bodies respectively.Sections sharing the same header are concatenated !
The header of an unnamed section is an empty string.importbraqtext="""\this is the unnamed section atthe top of this document...[section 1]this is section 1"""d=braq.parse(text)# check headersasserttuple(d.keys())==("","section 1")# check the body of 'section 1'assertd["section 1"]=="this is section 1"Parse a document iterativelyA document can be parsed line by line as following:importbraqtext="""\this is the unnamed section[section 1]this is section 1"""forheader,bodyinbraq.iter_parse(text):ifheader:print("["+header+"]")forlineinbody:print(line)Output:this is the unnamed section

[section 1]
this is section 1Back to topRead a fileThe library exposes thereadfunction which takes as input the path to a file to parse, then returns a dictionary whose keys and values are strings representing headers and bodies respectively.Sections sharing the same header are concatenated !importbraqpath="/home/alex/braqfile.txt"r=braq.read(path)asserttuple(r.keys())==("","section 1")Read a file iterativelyA large text file can be parsed line by line as following:importbraqpath="/home/alex/braqfile.txt"forheader,bodyinbraq.iter_read(path):ifheader:print("["+header+"]")forlineinbody:print(line)Output:this is the unnamed section

[section 1]
this is section 1Back to topRender a documentRendering a document involves transforming Python objects representing sections into Braq text which is a string that can be displayed on the screen or stored in a file.The library exposes therenderfunction which accepts as input a sequence of sections (either header-body tuples orSectionobjects) and returns a Braq document.importbraqsection_1=braq.Section("section 1","line a\nline b")section_2="section 2","line c\nline d"section_3="section 3",("line e","line f")r=braq.render(section_1,section_2,section_3)print(r)Output:[section 1]
line a
line b

[section 2]
line c
line d

[section 3]
line e
line fThe render function also accepts thespacingargument which defaults to 1 and represents the number of lines of spacing between two adjacent sections.Back to topWrite to fileFollowing is a snippet for writting a Braq document to a file:importbraq# sectionssection_1=braq.Section("","welcome")section_2=braq.Section("section 2")section_3="section 3",("line a","line b")# path to filepath="/home/alex/braqfile.txt"# write to filer=braq.write(section_1,section_2,section_3,dest=path)The contents of the Braq file:welcome

[section 2]

[section 3]
line a
line bBack to topThe Section classTheSectionclass is an abstraction representing a Braq section. It exposes theheaderandbodyproperties and renders itself when its__str__method is called implicitly.importbraqheader,body="my header",("line a","line b")section=braq.Section(header,body)assertsection.header=="my header"assertsection.body=="line a\nline b"assertstr(section)=="""\[my header]line aline b"""Back to topThe Parser classTheiter_parsefunction under the hood uses theParserclass to parse Braq documents.importbraqdoc="""\welcome[section 1]line aline b"""parser=braq.Parser()forheader,bodyinparser.parse(doc):ifheader:print("["+header+"]")forlineinbody:print(line)Output:welcome

[section 1]
line a
line bBack to topMisc functionsThecheck_headerfunction accepts a line of text as input and then returns a boolean to indicate whether this line is a header or not.importbraqline_1="[my header]"line_2="[this isn't a header] at all"assertbraq.check_header(line_1)isTrueassertbraq.check_header(line_2)isFalseTheget_headerfunction accepts a line of text as input and returns a string if the line is a header. Otherwise,Noneis returned.importbraqline_1="[my header]"line_2="[this isn't a header] at all"assertbraq.get_header(line_1)=="my header"assertbraq.get_header(line_2)isNoneBack to topMiscellaneousCollection of miscellaneous notes.Cover imageThe beautiful cover image is generated withCarbon.Back to topTesting and contributingFeel free toopen an issueto report a bug, suggest some changes, show some useful code snippets, or discuss anything related to this project. You can also directly emailme.Setup your development environmentFollowing are instructions to setup your development environment# create and activate a virtual environmentpython-mvenvvenvsourcevenv/bin/activate# clone the project then change into its directorygitclonehttps://github.com/pyrustic/braq.gitcdbraq# install the package locally (editable mode)pipinstall-e.# run testspython-munittestdiscover-f-stests-t.# deactivate the virtual environmentdeactivateBack to topInstallationBraqiscross-platform. It is built onUbuntuand should work onPython 3.5ornewer.Create and activate a virtual environmentpython-mvenvvenvsourcevenv/bin/activateInstall for the first timepipinstallbraqUpgrade the packagepipinstallbraq--upgrade--upgrade-strategyeagerDeactivate the virtual environmentdeactivateBack to topAbout the authorHello world, I'm Alex, a tech enthusiast ! Feel free to get in touch withme!Back to top