Citiți -l în: Español.
Citiți -l în: Français.
Dacă viața vă oferă o grămadă de fișiere Markdown pentru a analiza sau edita, vă încălziți mușchii Regex și mergeți? Ce zici de utilizarea mai multor instrumente specifice în schimb? În această postare, vom oferi o imagine de ansamblu asupra modalităților programatice de a analiza și edita fișierele Markdown: Markdown, R Markdown, Quarto, Hugo Files, îl numiți.
Ce este Markdown?
Markdown este un limbaj de marcare (Punny, Eh) creat de John Gruber și Aaron Swartz. Iată un exemplu:
# My first header Some content, with parts in **bold** or *italic*. Let me add a (link)(https://ropensci.org).
Diferite fișiere de marcare pot duce la aceeași ieșire, de exemplu, aceasta este echivalentă cu primul nostru exemplu:
My first header =============== Some content, with parts in __bold__ or _italic_. Let me add a (link)(https://ropensci.org).
Mai mult, există diferite arome sau Specificații (specificații) de marcajcare adaugă unele sintaxe extinse, cum ar fi emojis -urile scrise cu coloni.
Utilizatorii R vor interacționa în mod obișnuit cu diferite arome de marcare prin instrumentele lor obișnuite:
Multe instrumente care folosesc Markdown acceptă, de asemenea, Frontmatter: Metadate în partea de sus a fișierelor de marcare, de exemplu Yaml, Toml PR JSON. Iată un exemplu cu un frontmatter yaml:
--- title: My cool thing author: Myself --- Some content, *nice* content.
Cel mai adesea utilizatorii R vor scrie marcaj manual sau cu ajutorul unui editor, cum ar fi editorul vizual Positron sau Rstudio IDE Visual Editor. Dar uneori, cineva va trebui să creeze sau să editeze o grămadă de fișiere Markdown simultan, iar editarea tuturor acestor fișiere de mână este o pierdere de timp uriașă. Această postare pe blog vă va oferi resurse în R pe care le puteți folosi pentru a crea, analiza și edita documente de marcare, astfel încât să puteți deveni vrăjitorul marcaj pe care l -ați visat întotdeauna să deveniți 🧙!
Bucăți de cod și programare alfabetizată
În Markdown puteți adăuga bucăți de cod, care vor fi formatate și evidențiate în mod corespunzător, folosind următoarea sintaxă:
```r 1 + 1 ```
Instrumentele pentru programarea alfabetizată, cum ar fi Knitr (pentru R Markdown și Quarto), vă vor permite să adăugați bucăți de cod care vor fi executate pentru a reda documentul:
```{r}
#| label: my-chunk
#| echo: true
1 + 1
```
Ultima sintaxă, bucățile de cod executabile, nu sunt neapărat gestionate în mod corespunzător de instrumentele „normale” din afara raftului precum Pandoc. Acest lucru este ceva de care trebuie să țineți cont dacă aveți de -a face cu documente care conțin bucăți de cod executabile.
Instrumente de șablare pentru documentele pentru placa de cazan
Imaginează -ți că trebuie să creezi o grămadă de fișiere de marcare R diferite, de exemplu pentru ca elevii să se folosească ca exerciții personalizate. În acest caz, puteți crea un document pentru placă de cazan ca șablon și puteți crea diferitele sale versiuni de ieșire folosind un instrument de șablon.
Instrumentele de șablare includ:
Cel mai simplu exemplu de pachet Whisker vă poate aminti în plus de pachetul de lipici.
Un flux de lucru comun ar fi:
- Creați un șablon într -un fișier, unde piesele variabile sunt indicate prin șiruri precum
{{name}}. - Citiți acest șablon în R folosind, de exemplu, pachetul BRIO.
- Cartografierea pe setul dvs. de variabile, faceți șablonul folosind Whisker și salvați fiecare versiune într -un fișier folosind pachetul BRIO.
Exemplu
Iată un exemplu de fișier de marcare pe care îl putem folosi ca șablon:
---
title: "Homework assignment 1"
author: "{{name}}"
---
Create a normal distribution with a mean of {{mean}} and a standard deviation of {{sd}}:
```{r solution-1}
# hint: use the rnorm function
```
Folosind fluxul de lucru de mai jos, putem crea diferite documente de marcare corespunzătoare diferitelor studenți.
# generate student variables ----
students <- c("Maëlle", "Christophe", "Zhian")
n <- length(students)
key <- data.frame(
name = students,
mean = rpois(n, 5),
sd = sprintf("%.1f", runif(n)),
file = sprintf("%s-hw.md", students)
)
# render and write assignment from template ----
make_assignment <- function(key, template) {
lapply(seq(n), function(i) {
new <- whisker::whisker.render(template, data = key(i, ))
brio::write_lines(new, key$file(i))
})
return(invisible())
}
md <- brio::read_lines("hw-template.md")
make_assignment(key, template = md)
print(key)
#> name mean sd file
#> 1 Maëlle 3 0.9 Maëlle-hw.md
#> 2 Christophe 4 0.2 Christophe-hw.md
#> 3 Zhian 8 0.8 Zhian-hw.md
Iată cum arată temele lui Zhian:
---
title: "Homework assignment 1"
author: "Zhian"
---
Create a normal distribution with a mean of 8 and a standard deviation of 0.8:
```{r solution-1}
# hint: use the rnorm function
```
Instrumente de manipulare a șirilor
Puteți utiliza instrumente de manipulare a șirilor pentru a analiza marcajul dacă sunteți sigur de variantele de marcare a codului dvs. va primi ca intrare sau dacă sunteți dispus să vă dezvoltați codul pentru a găzdui multe cazuri de margine … ceea ce în final înseamnă că scrieți un analizor de marcaj real. Nu pentru cei slabi de inimă … și nici nu este necesar dacă citiți secțiunea după aceasta. 😌
Ați detecta titluri folosind, de exemplu, grep("^#", markdown_lines).
Exemplu de instrumente de manipulare a șirului includ baza R (sub(), grep() și prieteni), Stringr (și Stringi), xfun::gsub_file().
Deși instrumentele de manipulare a șirurilor sunt de o utilitate limitată atunci când analizează marcajul, acestea pot completa Instrumentele de analiză reale. Chiar dacă utilizarea unor instrumente specifice de analiză a marcajului vă va ajuta să scrieți singuri mai puține expresii obișnuite … nu vă vor elibera complet de ele.
Instrumente de manipulare a reprezentării abstracte
Instrumentele de manipulare a reprezentării abstracte sunt fantastice și numeroase. Acestea traduc documentul de marcare într-o structură de date numită arbore de sintaxă abstractă (AST) care vă oferă un control cu granulație fină asupra elementelor specifice ale documentului (de exemplu, titluri individuale sau legături, indiferent de modul în care acestea sunt scrise). Cu o structură formală de date, puteți manipula programatic documentul de marcare prin adăugarea, eliminarea sau manipularea pieselor de marcare într -un mod standardizat.
Unele dintre aceste instrumente vă permit să citiți, să editați și scrie înapoi la document.
Vom menționa doar instrumentele pe care le puteți utiliza direct de la R.
Exemplu de utilizare a cazului
Să zicem că ați creat o grămadă de tutoriale care se leagă de un site web care conține o galerie de extensii pentru un pachet popular de complot. Să spunem, de asemenea, că într -o zi, cineva descoperă că linkul către site -ul web se redirecționează brusc către un site potențial rău, care, cu siguranță, nu are legătură cu gramatica graficelor și trebuie să înlocuiți toate cazurile de legătură cu acest link **redacted**. Deoarece legăturile din Markdown ar putea fi scrise în orice mod de moduri, Regex nu vă va ajuta, dar un analizor cu granulație fină o va face!
Un flux de lucru pentru această situație ar fi:
- Citiți în marcajul AST cu parserul dvs. preferat
- Scoateți toate legăturile care indică linkul putred
- Înlocuiți -le cu textul accentuat care spune „redactat”
- Convertiți AST și scrieți înapoi în fișier
{tinkr}
Pachetul Tinkr visat de Maëlle Salmon și întreținut de Zhian Kamvar Parses Markdown către XML folosind CommonMark, vă permite să extrageți și să manipulați Markdown folosind XPath prin intermediul pachetului XML2. Tinkr scrie XML înapoi la Markdown folosind XSLT. Metadatele YAML sunt disponibile ca șir. Tinkr acceptă bucăți de cod executabile.
Pachetul Tinkr este utilizat în pachetele Babeldown și Aeolus.
{md4r}
Pachetul MD4R, este un pachet experimental recent menținut de Colin Rundel și este un ambalaj R în jurul bibliotecii MD4C (Markdown for C) și reprezintă AST -ul ca o listă cuibărită cu atribute în R. Versiunea de dezvoltare a pachetului are utilități pentru construirea documentelor marcajului programatic.
Pandoc
Cu Pandoc pe care l -am prezentat într -o notă tehnologică, puteți analiza fișierele de marcare la un arbore de sintaxă abstract Pandoc (fie în formatul său nativ, fie în JSON).
Cum ați folosi Pandoc pentru a edita și scrie înapoi un fișier de marcare?
-
Folosind filtre LUA: Pandoc se transformă în AST în formatul său nativ, filtrele LUA permit să -l proceseze pentru a -l regla, iar PanDoc poate scrie înapoi la Markdown.
-
Utilizarea filtrelor JSON: PANDOC se transformă în AST care iese o reprezentare JSON a acesteia, apoi orice instrumente poate modifica acest fișier JSON și a furnizat o versiune modificată în PANDOC pentru a converti înapoi la Markdown.
Rețineți că PANDOC nu acceptă bucăți de cod executabile, deoarece nu va putea analiza codul executabil, deoarece Codeblock.
{parseqmd}
Nic Crane are un pachet experimental numit Parseqmd care folosește această strategie, analizând producția cu pachetul JSONLITE. De asemenea, puteți analiza, să spuneți HTML, apoi să vă întoarceți la Markdown. Avantajul analizării la HTML este că puteți utiliza un pachet precum XML2 sau RVEST pentru a extrage și manipula elementele.
{parsermd}
Pachetul Parsermd este un alt pachet menținut de Colin Rundel și este o „implementare a unei gramatici formale și parser pentru documentele R Markdown folosind Biblioteca Boost Spirit X3. De asemenea, include o colecție de funcții de nivel înalt pentru lucrul cu arborele de sintaxă abstract rezultat.”
Acest pachet are funcționalitate pentru un flux de lucru ordonat care vă permite să selectați diferite secțiuni ale documentului. O caracteristică utilă este că are funcția rmd_check_template() permițându -vă să comparați departamentul de marcare a studenților cu un șablon standard. Puteți urmări Rstudio :: conf (2021) să vorbească despre asta.
Pachetul Parsermd vă permite chiar să modificați documentele.
{LightParser}
Pachetul LightParser de Sébastien Rochette „Împarte fișierele dvs. Rmarkdown sau Quarto prin secțiuni într -un tibble: titluri, text, bucăți; reconstruiește fișierul din tibble”. Poate fi utilizat pentru a traduce documente, de exemplu.
Imposibilitatea unui rotund perfect
La analizarea și editarea marcajului, apoi scrieți -l înapoi la Markdown, s -ar putea să apară unele modificări nedorite. De exemplu, cu elementele din lista Tinkr, toate încep cu un - chiar dacă în documentul original au început cu un *. Cu MD4R, listele care sunt indentate cu spațiu suplimentar vor fi reajustate.
În funcție de cazul dvs. de utilizare, este posibil să doriți să găsiți modalități de atenuare a acestor pierderi, de exemplu, rescrierea doar a liniilor la care ați făcut modificări intenționate.
Cum să alegi un parser?
Puteți alege un analizor pe baza a ceea ce vă permite să manipulați marcajul cu: dacă preferați XML și HTML pe liste cuibărite, de exemplu, este posibil să preferați să utilizați Tinkr sau Pandoc. Dacă funcțiile la nivel înalt ale MD4R sau Parsermd sunt potrivite pentru carcasa dvs. de utilizare, este posibil să preferați unul dintre ei.
Important, dacă documentele dvs. conțin bucăți de cod executabile, trebuie să utilizați un instrument care să le accepte, cum ar fi Parsermd, LightParser, Tinkr.
Ce zici de bucățile de cod?
Analizarea programatică și editarea codului R este în afara domeniului de aplicare al acestui post, dar suficient de legat de a arunca câteva sfaturi.
Expresii obișnuite
Ca și în cazul Markdown, este posibil să fie nevoie să utilizați expresii obișnuite, dar aceasta este o abordare riscantă, de exemplu plot (x) şi plot(x) sunt ambele apeluri funcționale valide în R.
{xmlparsedata}
Puteți analiza codul către XML folosind baze R Parsing și XMLPARSEDATA, apoi manipulați XML cu XPath. Pentru a scrie codul înapoi, puteți folosi atributele fiecărui nod care indică liniile și coloanele originale.
Deci, un posibil flux de lucru, așa cum este exemplificat în postarea de pe blogul lui Maëlle este:
- Analizați codul la XML, utilizați XMLPARSEDATA pentru a informa ce să schimbați și unde. Din acești pași, veți primi o listă de poziții ale elementelor, de exemplu.
- Folosiți Brio pentru a citi liniile, schimbați câteva dintre ele cu instrumente R de bază, apoi folosiți din nou Brio pentru a scrie liniile înapoi.
{Treesitter}
Treesitter de Davis Vaughan „oferă legături R la arbori, un sistem de analiză incremental”.
Dar metadatele?
Am dedicat această postare întreagă corp de documente de marcare. Ce zici de metadatele conținute în frontul lor, cum ar fi:
--- title: "Cool doc" author: "Jane Doe" ---
Pentru a extrage sau edita metadatele YAML/Toml/JSON, mai întâi trebuie să decapitați documentele de marcare. De exemplu, Rmarkdown are o funcție numită rmarkdown::yaml_front_matter() pentru a extrage metadatele YAML ale unui document de marcare R; Pachetul quarto r are o funcție numită quarto::quarto_inspect() că, printre altele, rezultă metadatele.
S -ar putea să citiți linii a documentului de marcare folosind readLines() sau brio::read_lines()înainte de a recurge la expresii obișnuite pentru a identifica începutul și capătul frontmatter -ului, în funcție de formatul său.
Apoi, pentru a gestiona yaml, ați folosi {yaml}, pentru a gestiona Toml, puteți utiliza {Tomledit} sau {rcpptoml}, pentru a gestiona JSON, puteți folosi {jsonlite}.
În cele din urmă, dacă trebuie să scrieți înapoi documentul Markdown, ați scrie înapoi liniile sale folosind writeLines() sau brio::write_lines().
Exemple de analiză și editare a marcajului
Pachetul Pegboard creat de Zhian Kamvar și întreținut de Carpentries, Parses și validează lecțiile Carpentries pentru elementele de marcare structurală, inclusiv legături valide, alt-text și divizii împrejmuite cunoscute datorită TINKR. Acest pachet a contribuit la transformarea tuturor infrastructurii de lecție de tâmplărie de la sintaxa de marcare a lui Jekyll în Markdown de la Pandoc.
Pachetul Babeldown întreținut de Maëlle Salmon transformă Markdown în XML, îl trimite în API -ul Deepl pentru traducere și scrie rezultatele înapoi la Markdown, folosind și Tinkr.
Concluzie
În această postare am explicat cum să analizăm și să edităm fișierele de marcare. Pentru a crea documente pentru placă knitr::knit_expand()pachetul Whisker, pachetul Brew, Pandoc. Pentru a edita părți mici ale unui document, am adus instrumente de manipulare a șirurilor, adică expresii obișnuite, cu baza R (sub(), grep() și prieteni), Stringr (și Stringi), xfun::gsub_file(). Pentru o manipulare mai grea și mai sigură, am enumerat instrumente pe baza instrumentelor care manipulează reprezentarea abstractă a documentelor: Tinkr, MD4R, Pandoc, Parseqmd, Parsermd, LightParser. Am menționat și instrumente pentru lucrul cu Cod R. în interiorul celulelor de cod și pentru lucrul cu YAML/Toml/JSON Frontmatter.
Ce face tu Utilizați pentru a gestiona fișierele Markdown?
