README

Hashdown读取并解析格式严格的.md文件到PHP数字或关联数组 - 或者将PHP数组或对象写入到结构化的.md文件。

为什么？

Markdown作为文档语法的优点已被广泛认可 - 但Markdown在序列化和编辑任意数据方面也提供了优势。例如，与YAML和JSON不同，Markdown的层次结构标题结构不依赖于缩进或括号 - 使得在编辑具有多行值的时，Markdown往往是一个更佳的解决方案。Markdown的代码块语法还允许轻松转义更复杂的内容。

它的工作原理

在Hashdown格式中，Markdown文档中的每个标题都代表关联数组中的一个键，其中标题之后对应的内容代表该键的值。例如，以下.md内容将生成下面的PHP关联数组

# Name of Food
Twinkie

# Serving size
2 cakes

# Calories per serving
280

[
  'Name of Food' => 'Twinkie',
  'Serving size' => 2 cakes,
  'Calories per serving' => 280,
]

H1s (#) 成为顶级键，而H2s (##) 成为二级键，以此类推

# Serving size
## Amount
2

## Unit
Cakes

上面的内容变为

[
  'Serving size' => [
    'Amount' => '2',
    'Unit' => 'Cakes',
  ]
]

跳过标题级别（例如，从#跳转到###）是不允许的，因为这会创建一个无效的数组。

列表和顺序数组

Markdown标题也可以用于生成顺序（而不是关联）数组。没有内联文本的标题（例如一个单独的hash #）将简单地递增键。以下两个文档是等价的，并对应下面的PHP数组

# Ingredients
##
sugar
##
water
##
enriched flour

# Ingredients
## 0
sugar
## 1
water
## 2
enriched flour

[
  'Ingredients' => [
    'sugar',
    'water',
    'enriched flour',
  ]
]

对于具有标量值的列表项（如上面所示），可以使用短语的“破折号”（-）语法代替hash（#）。下面的.md文档与上述两个文档等价

# Ingredients
- sugar
- water
- enriched flour

"破折号"样式列表值可以跨越多行。以下列表是有效的，与下面的PHP数组等价

- first line,
second line

-
another list item
with multiple lines

[
  'first line,\nsecond line',
  'another list item\nwith multiple lines'
]

但非标量值必须在“hash”样式标题下。下面的第一个例子是有效的，但第二个不是，因为所需的数据结构可能变得模糊不清

#
## Name
Twinkie
## Ingredients
- sugar
- water

#
## Name
Diet Coke

-
## Name
Twinkie
## Ingredients
- sugar
- water

-
## Name
Diet Coke

文字和代码块

转义嵌入的Markdown语法

如果您需要在.md文档中代表Markdown作为标量内容，您可以使用Markdown的代码块语法进行转义。

"文字"或"代码块"部分由三个或更多引号(```)指定。下面的data键有一个名为title的子节点，而content节点只是一个Markdown文本的字符串

# data
## title
A Tale of Two Cities
# content
```
# Chapter 1
It was the best of times...
```

表示空白

通常，Hashdown忽略空行和前导或尾随空格。例如，以下两个文档是等价的，因为第二个文档中的空格和空行将被Hashdown解析器删除/忽略

# key
some text
some more text

# key
  some text


some more text

然而，如果放置在“文字”块中，前导空格和空行将被保留

# key
```
  some text


some more text
```

转义/嵌套文字

文字可以嵌套在文字中。最外层必须具有最多的引号。如果一个文字以5个引号开始，那么直到下一行有5个引号的任何东西都是可以的

`````
# This is a literal initiated with 5 tick marks

````
# this is a nested literal, designated by 4 tick marks

```
# this is a doubly nested literal, designated by 3 tick marks

```
````
`````
# This is outside the literal, since the line above has 5 tick marks

代码示例

从.md文件中读取

使用Hashdown的静态x_read_file方法从文件中读取/反序列化.md文件

use Neckberg\Hashdown\Hashdown;

$x_groceries = Hashdown::x_read_file( '.../Groceries.md' );

给定以下Groceries.md文档，上述代码将$x_groceries设置为下面的PHP数组

# Groceries
##
### Name
Twinkie
### Ingredients
- sugar
- water
- enriched flour

##
### Name
Diet Coke
### Ingredients
- carbonated water
- caramel color
- aspartame

[
  'Groceries' => [
    'Name' => 'Twinkie',
    'Ingredients' => [
      'sugar',
      'water',
      'enriched flour',
    ],
    'Name' => 'Diet Coke',
    'Ingredients' => [
      'carbonated water',
      'caramel color',
      'aspartame',
    ],
  ],
];

写入.md文件

使用Hashdown的静态write_to_file方法写入.md文件。

下面的PHP代码将生成以下内容的Groceries.md文件

use Neckberg\Hashdown\Hashdown;

$x_groceries = [
  'Groceries' => [
    'Name' => 'Twinkie',
    'Ingredients' => [
      'sugar',
      'water',
      'enriched flour',
    ],
    'Name' => 'Diet Coke',
    'Ingredients' => [
      'carbonated water',
      'caramel color',
      'aspartame',
    ],
  ],
];
Hashdown::write_to_file($x_groceries, '.../Groceries.md');

# Groceries
## 0
### Name
Twinkie

### Ingredients
- sugar
- water
- enriched flour

## 1
### Name
Diet Coke

### Ingredients
- carbonated water
- caramel color
- aspartame

格式化选项

默认情况下，write_to_file将使用简写“短横线”列表和明确编号的顺序数组项（如上所示）。但此行为可以通过第3和第4个参数进行更改。

b_no_shorthand_lists，布尔值：如果为true，则不使用任何列表的简写“短横线”语法。仅使用“井号”语法。
b_omit_numeric_array_keys，布尔值：如果为true，则省略顺序数字数组的显式键值。

假设上面定义了相同的$x_groceries变量，以下调用将产生下面的输出

允许简写“短横线”列表，但在可能的情况下省略顺序键

Hashdown::write_to_file($x_groceries, '.../Groceries.md', false, true);

# Groceries
##
### Name
Twinkie

### Ingredients
- sugar
- water
- enriched flour

##
### Name
Diet Coke

### Ingredients
- carbonated water
- caramel color
- aspartame

仅允许“井号”风格列表，但显示显式的顺序键号

Hashdown::write_to_file($x_groceries, '.../Groceries.md', true, false);

# Groceries
## 0
### Name
Twinkie

### Ingredients
#### 0
sugar

#### 1
water

#### 2
enriched flour

## 1
### Name
Diet Coke

### Ingredients
#### 0
carbonated water

#### 1
caramel color

#### 2
aspartame

仅允许“井号”风格列表，并在可能的情况下省略顺序键

Hashdown::write_to_file($x_groceries, '.../Groceries.md', false, false);

# Groceries
##
### Name
Twinkie

### Ingredients
####
sugar

####
water

####
enriched flour

##
### Name
Diet Coke

### Ingredients
####
carbonated water

####
caramel color

####
aspartame

测试

切换到目录
运行composer install
运行vendor/bin/phpunit

neckberg / hashdown

维护者

详情